zelkova_compiler/canonical/

mod.rs

//! The canonical representation of a zelkova programs is a translation of a local
//! source into the broader world.
//!
//! This phase is where we integrate the local parsed module into the rest of the
//! program. We do the following steps:
//!
//! - Resolve all imports
//! - Qualify all `Name` (eg. a local value `test` in a `Mod.A` module will be renamed `Mod.A.test`)
//! - Checks that exported names are actually present in the module
//! - Checks there is none cyclic dependency between this module and others (Might be done earlier, let's see)
//!
//! Note that we use `HashMap`'s a lot in this module's structures. This is because later phases will
//! want to have cheap access to the different components of a `Module`.
//!
//! TODO Rename this to core ? I feel it's going to be te main internal representation of the language.
use super::resolve::CORE_PACKAGE;
use super::scalars;
use super::Interface;
use super::PhaseError;
use super::SpanLabel;
use super::{ModuleName, PackageName};
use crate::utils::{collect_accumulate, collect_partial};
use log::{debug, trace};
use petgraph::graph::{DiGraph, NodeIndex};
use petgraph::Direction;
use std::cmp::Reverse;
use std::collections::BinaryHeap;
use std::collections::{BTreeMap, HashMap, HashSet};
use zelkova_syntax::parser;

mod classes;
pub use classes::{
    Class, ClassSignature, Constraint, DeclarationSite, Derivation, DerivationBindings,
    DerivationRole, HeadName, Instance, InstanceHead, InstanceName, InstanceSignature, Member,
    PublishedInstance,
};
mod derivation;
pub use derivation::{
    DerivationSignatureProblem, DerivedContextGap, DerivedPart, DerivedRequirement,
    DerivedShapeProblem,
};
mod environment;
/// Part of [`Error::AmbiguousVariables`] and [`Error::AmbiguousVariants`]'s public
/// shape, so it is re-exported alongside the error rather than left behind a
/// private module.
pub use environment::ImportOrigin;
/// Part of [`Error::AmbiguousOperatorPrecedence`]'s public shape, so it is
/// re-exported alongside the error rather than left behind a private module.
pub use environment::InfixDeclaration;
use environment::{
    new_environment, suggest_name, EnvError, Environment, InfixFunction, RootEnvironment, ValueType,
};

// Some elements which are common to both AST
use crate::name::{Name, QualName};
use crate::source::files::SourceFileId;
pub use parser::Associativity;
use zelkova_syntax::position::NodeSpan;
use zelkova_syntax::tuple::Tuple;

// begin AST

/// A resolved module
#[derive(Debug)]
pub struct Module {
    pub name: ModuleName,
    pub exports: Exports,
    /// Where the header's `exposing (...)` was written — `parser::Module::exposing_span`,
    /// carried through. A diagnostic about what the module exposes as a whole points here.
    pub exposing_span: NodeSpan,
    /// Operator name to infix details
    pub infixes: HashMap<Name, Infix>,
    pub types: HashMap<Name, UnionType>,
    /// Every `class` declaration that canonicalized, by name. A member is not in
    /// [`values`](Self::values): it has a signature and no body, and the class carries it.
    pub classes: HashMap<Name, Class>,
    /// Every `instance` declaration that passed every check, in source order.
    pub instances: Vec<Instance>,
    /// Every instance this module's imports brought into scope, each once.
    /// [`to_interface`](Self::to_interface) publishes them beside the module's own, which
    /// is what carries an instance to every module that can reach its declaring one.
    pub imported_instances: Vec<PublishedInstance>,
    pub values: HashMap<Name, Value>,
    /// The value declarations that were written and have no canonical form, sorted by name.
    ///
    /// A declaration is here when its annotation or its body did not canonicalize, or, in
    /// a facade, when its signature was rejected by the per-declaration checks; an error
    /// beside the module says which. It is also here when a declaration chunk that failed
    /// to parse names it ([`parser::Module::failed`]), whatever else of it parsed; the
    /// syntax error says why, and only its annotation, when one parsed, is checked. The
    /// checks that run on the whole signature list before those (`FacadeConstrained` and
    /// a facade's malformed context, `UnsafeOutsideFacade`) report an error and leave the
    /// declaration where the per-declaration checks put it. Outside a facade, a context
    /// is part of its annotation, and a declaration whose context does not resolve is
    /// here with no type.
    /// Every other value declaration is in [`values`](Self::values), and no name is in
    /// both. What survives of one is its annotation, when that canonicalized:
    /// [`to_interface`](Self::to_interface) exposes it and the typer declares it, so a
    /// caller of a broken declaration is checked against the type it was written with.
    pub broken: Vec<Broken>,
    /// True when this module is a `module foreign` facade.
    /// Such modules have synthetic placeholder bodies and must not be type-checked.
    pub binding_foreign: bool,
    /// Whether a name could be missing from this module for a reason already reported.
    ///
    /// Set when the module's scope ended incomplete: an import did not resolve, an
    /// import resolved to an [`Interface`] whose own
    /// [`incomplete`](Interface::incomplete) is set, a `type`, `infix`, `class` or
    /// `instance` declaration failed, or a declaration chunk that names nothing failed to
    /// parse. Also set when a
    /// value declaration was written with an annotation that did not canonicalize, or is
    /// named by a chunk that failed to parse and has no type, since its annotation may be
    /// that chunk: those are the two ways a name goes missing from
    /// [`to_interface`](Self::to_interface) while the module's own scope is whole.
    /// [`to_interface`](Self::to_interface) copies it to [`Interface::incomplete`].
    pub incomplete: bool,
}

/// A value declaration canonicalization rejected, recorded in [`Module::broken`].
#[derive(Debug, Clone, PartialEq)]
pub struct Broken {
    pub name: Name,
    /// Where the declaration was written, annotation and body together.
    pub span: NodeSpan,
    /// The type of the declaration's annotation, when it has one and both that type and
    /// its context canonicalized; `None` when either failed.
    pub tpe: Option<Type>,
    /// The constraints written in front of that annotation's `=>`, each resolved, in
    /// the order written; empty when `tpe` is `None`. Beside the type and not inside
    /// it, as on [`Value::TypedValue`].
    pub context: Vec<Constraint>,
    /// Where that annotation was written; `NodeSpan::none()` when `tpe` is `None`.
    pub annotation_span: NodeSpan,
}

impl Broken {
    /// `function`, recorded as broken, with `annotation` as its annotation's type and
    /// context when those canonicalized.
    fn of(function: &parser::Function, annotation: Option<(Type, Vec<Constraint>)>) -> Broken {
        let (tpe, context, annotation_span) = match annotation {
            Some((tpe, context)) => (Some(tpe), context, function.annotation_span),
            None => (None, Vec::new(), NodeSpan::none()),
        };

        Broken {
            name: function.name.clone(),
            span: function.span,
            tpe,
            context,
            annotation_span,
        }
    }
}

/// What an [`Interface`] publishes of a value: where it was declared, its type, and the
/// constraints its annotation wrote in front of that type.
///
/// One struct rather than a map per field, so an entry cannot have a type and lack the
/// context it was written with: an importer's call to a constrained function is checked
/// against this entry, and an empty [`context`](Self::context) here means the function
/// is unconstrained.
#[derive(Debug, Clone, PartialEq)]
pub struct ValueSignature {
    /// Where the declaration (annotation and body together) was written —
    /// [`Value::span`] — so a diagnostic about a name found in an interface can point at
    /// the declaration, not just name it.
    pub span: NodeSpan,
    /// The annotation's resolved constraints, in the order written.
    pub context: Vec<Constraint>,
    pub tpe: Type,
}

impl ValueSignature {
    /// The signature of a value declared at `span` with the type `tpe` and no
    /// constraint.
    pub fn unconstrained(span: NodeSpan, tpe: Type) -> ValueSignature {
        ValueSignature {
            span,
            context: Vec::new(),
            tpe,
        }
    }
}

/// What [`canonicalize_recovering`] built of a module, beside every error it reported.
#[derive(Debug)]
pub struct Canonicalized {
    /// The module, holding every declaration that canonicalized. A value declaration
    /// that did not is in [`Module::broken`]; a `type`, `infix`, `class` or `instance`
    /// declaration that did not is in neither.
    pub module: Module,
    /// Every error canonicalization reported. Empty exactly when [`canonicalize`] would
    /// answer `Ok` with [`module`](Self::module).
    ///
    /// An error is left out of it only when another stands behind it: a not-found error
    /// raised in an [incomplete](Module::incomplete) scope restates the failure that made
    /// the scope incomplete (`without_restated`), and nothing about a declaration a chunk
    /// that failed to parse names is said beyond its annotation's own errors, since the
    /// syntax error stands for it. A declaration that every error was left out of is
    /// either still absent from the module, because the error broke it, or present holding
    /// a hole for a name that did not resolve ([`Value::holds_hole`]). So empty here does
    /// not mean [`Module::broken`] is empty, that [`Module::incomplete`] is false, nor that
    /// no value holds a hole.
    pub errors: Vec<Error>,
}

impl Module {
    /// Build the trimmed-down view of this module other modules import against.
    ///
    /// `file` is the [`SourceFileId`] this module was read from, which is what lets
    /// a later module's diagnostic point back into *this* module's source — see
    /// [`Interface::file`](super::Interface::file). It is a parameter rather than
    /// something this method could work out because a `canonical::Module` does not
    /// know it: only driver code does, and the sole caller
    /// (`dependencies::ModuleWalker::check_in_order`) is driver code that has the
    /// map from module name to file in hand. A caller with nothing to give — every
    /// test that hand-builds an interface — passes `None`, and
    /// [`Interface::source_span`](super::Interface::source_span) then declines to
    /// build a cross-module label rather than building one at the wrong place.
    ///
    /// # What the `exposing (...)` header removes here
    ///
    /// This is the only place a module's own [`Exports`] is read, and reading it
    /// here is what makes a declaration left out of the header private (`BUG-9`).
    /// `self.values`, `self.types` and `self.infixes` stay complete — the typer,
    /// exhaustiveness and every later phase run against the whole
    /// [`Module`](Self), because a private declaration is still callable from
    /// inside the module that wrote it. Only this external view is trimmed, and
    /// only by three rules:
    ///
    /// - a value reaches the interface when the header exposes its name as
    ///   [`ExportType::Value`], on top of the requirement that it carry a type
    ///   annotation (`Value::TypedValue`). `do_exports` reports an exposed,
    ///   unannotated declaration (`SPEC-5`), and the declaration is left out
    ///   here. A [`Broken`] declaration the header exposes reaches the
    ///   interface the same way when its annotation canonicalized, with that
    ///   annotation as its type, so an importer is checked against it;
    /// - an infix reaches it when the header exposes the operator;
    /// - a union type reaches it when the header names it either way, but a
    ///   `Size` entry ([`ExportType::UnionPrivate`]) hands over the declaration
    ///   with its `variants` emptied, and records its name in
    ///   [`Interface::opaque_unions`]. That is the opaque type: importers still
    ///   get the name and its type variables — [`Interface::unions`] is where
    ///   `process_import`'s `Privacy::Private` arm reads the arity from — and no
    ///   constructor to build or match one with.
    ///
    /// A class reaches it, with every member and the derivations it carries, when the
    /// header names it ([`ExportType::Class`]).
    ///
    /// [`Exports::Everything`] — a `exposing (..)` header — exposes every
    /// declaration with every constructor, so nothing is dropped in that case.
    ///
    /// # What the header does not remove
    ///
    /// Every instance reaches the interface: the module's own, and every one its imports
    /// brought into scope ([`imported_instances`](Self::imported_instances)). An instance
    /// has no name for a header to list, and it has to be in scope in every module that
    /// can reach the module declaring it, through however many imports, so each module
    /// passes on what it received
    /// ([Type classes](../../docs/spec/type-classes.md#declaring-an-instance)).
    ///
    /// An exposed infix whose backing function is not itself separately exposed
    /// — `infix left 6 (+) = add` with `(+)` in the header and `add` not, which
    /// is every operator `std/core` declares — still needs `add`'s type
    /// reachable, or an importer that brings `(+)` into scope has no type to
    /// give a use of it. [`Interface::infix_functions`] carries exactly that,
    /// kept out of `values` itself so `add` stays unreachable under its own
    /// name.
    pub fn to_interface(&self, file: Option<SourceFileId>) -> super::Interface {
        let values: HashMap<Name, ValueSignature> = self
            .values
            .keys()
            .chain(self.broken.iter().map(|broken| &broken.name))
            .filter(|name| self.exports.exposes(name, &ExportType::Value))
            // An exposed, unannotated declaration is an error `do_exports` has reported
            // (`SPEC-5`, `BUG-14`); it has no type to publish, and neither has a broken
            // one whose annotation did not canonicalize.
            .filter_map(|name| self.declared_signature(name))
            .collect();

        let mut opaque_unions = HashSet::new();
        let unions = self
            .types
            .iter()
            .filter_map(|(name, union)| match self.exports.union_visibility(name) {
                UnionVisibility::Hidden => None,
                UnionVisibility::Transparent => Some((name.clone(), union.clone())),
                UnionVisibility::Opaque => {
                    opaque_unions.insert(name.clone());
                    Some((
                        name.clone(),
                        UnionType {
                            variables: union.variables.clone(),
                            variants: Vec::new(),
                            span: union.span,
                        },
                    ))
                }
            })
            .collect();

        let infixes: HashMap<Name, Infix> = self
            .infixes
            .iter()
            .filter(|(name, _)| self.exports.exposes(name, &ExportType::Infix))
            .map(|(name, infix)| (name.clone(), infix.clone()))
            .collect();

        // See `Interface::infix_functions`'s doc comment: only a backing function
        // *not* already reaching `values` on its own needs a supplementary entry
        // here — one that is already exposed by name is inserted twice
        // otherwise, which `insert_foreign_value` reads as the same value
        // imported from two places.
        let infix_functions: HashMap<Name, ValueSignature> = infixes
            .values()
            .filter(|infix| !values.contains_key(&infix.function_name))
            .filter_map(|infix| self.declared_signature(&infix.function_name))
            .collect();

        // A broken value has no parameters to count, so it gets no entry; an importer
        // reads its absence as arity 0 (see `Interface::arities`).
        let arities = values
            .keys()
            .chain(infix_functions.keys())
            .filter_map(|name| {
                self.values
                    .get(name)
                    .map(|value| (name.clone(), self.emitted_arity(value)))
            })
            .collect();

        let classes = self
            .classes
            .iter()
            .filter(|(name, _)| self.exports.exposes(name, &ExportType::Class))
            .map(|(name, class)| (name.clone(), class.signature.clone()))
            .collect();

        let instances = self
            .instances
            .iter()
            .map(|instance| PublishedInstance {
                signature: instance.signature.clone(),
                source: file.and_then(|file| {
                    instance
                        .signature
                        .span
                        .span()
                        .map(|span| super::SourceSpan { file, span })
                }),
            })
            .chain(self.imported_instances.iter().cloned())
            .collect();

        super::Interface {
            module_name: self.name.clone(),
            values,
            unions,
            opaque_unions,
            infixes,
            infix_functions,
            arities,
            classes,
            instances,
            file,
            incomplete: self.incomplete,
        }
    }

    /// The annotation this module declares `name` with, context included, and where the
    /// declaration was written: an annotated value's, or a [`Broken`] one's whose
    /// annotation canonicalized.
    fn declared_signature(&self, name: &Name) -> Option<(Name, ValueSignature)> {
        let signature = match self.values.get(name) {
            Some(Value::TypedValue {
                tpe, context, span, ..
            }) => ValueSignature {
                span: *span,
                context: context.clone(),
                tpe: tpe.clone(),
            },
            Some(Value::Value { .. }) => return None,
            None => {
                let broken = self.broken.iter().find(|broken| &broken.name == name)?;
                ValueSignature {
                    span: broken.span,
                    context: broken.context.clone(),
                    tpe: broken.tpe.clone()?,
                }
            }
        };

        Some((name.clone(), signature))
    }

    /// How many parameters `value`, one of this module's declarations, is emitted with:
    /// the count a call has to supply to be a direct call.
    ///
    /// For a declaration with a body that is [`Value::arity`], the parameters it was
    /// written with. A `module foreign` facade's declaration is a signature with no
    /// parameters to count, and its forwarding function takes one parameter per arrow in
    /// the signature ([`Type::arrow_count`]), the [plain parameter
    /// list](../../docs/spec/interop.md#the-javascript-companion) its companion's
    /// export takes.
    ///
    /// [`to_interface`](Self::to_interface) records it for each exported value, so that
    /// an importer's call site is saturated at the same count this module's own call
    /// sites are.
    pub fn emitted_arity(&self, value: &Value) -> usize {
        match value {
            Value::TypedValue { tpe, .. } if self.binding_foreign => tpe.arrow_count(),
            value => value.arity(),
        }
    }
}

#[derive(Debug, PartialEq)]
pub enum Exports {
    Everything,
    /// Non qualified name to its export type
    Specifics(HashMap<Name, ExportType>),
}

impl Exports {
    /// Whether the `exposing (...)` header exposes `name` *as* `kind`.
    ///
    /// The kind is part of the question rather than a detail of the answer
    /// because the three namespaces a module exports into are separate: a
    /// header naming `map` exposes the value `map`, and says nothing about an
    /// operator or a type that happened to share the spelling. Union types ask
    /// [`union_visibility`](Self::union_visibility) instead, which has a third
    /// answer for the opaque case.
    pub(crate) fn exposes(&self, name: &Name, kind: &ExportType) -> bool {
        match self {
            Exports::Everything => true,
            Exports::Specifics(specifics) => specifics.get(name) == Some(kind),
        }
    }

    /// How far a union type declared in this module crosses the module boundary.
    fn union_visibility(&self, name: &Name) -> UnionVisibility {
        match self {
            Exports::Everything => UnionVisibility::Transparent,
            Exports::Specifics(specifics) => match specifics.get(name) {
                Some(ExportType::UnionPublic) => UnionVisibility::Transparent,
                Some(ExportType::UnionPrivate) => UnionVisibility::Opaque,
                Some(ExportType::Value)
                | Some(ExportType::Infix)
                | Some(ExportType::Class)
                | None => UnionVisibility::Hidden,
            },
        }
    }
}

/// The three answers [`Exports::union_visibility`] can give for one of the
/// module's own union types, in the order a reader of an `exposing (...)` list
/// meets them: no entry at all, a bare `Size` entry, a `Size(..)` entry.
#[derive(Debug)]
enum UnionVisibility {
    /// Not in the header: other modules cannot name the type at all.
    Hidden,
    /// `Size` — the type's name and arity cross the boundary, its constructors
    /// do not.
    Opaque,
    /// `Size(..)` — the declaration crosses whole, constructors included.
    Transparent,
}

#[derive(Debug, PartialEq)]
pub enum ExportType {
    Value,
    Infix,
    UnionPublic,
    UnionPrivate,
    /// A class, named bare in the header, which exposes it with every member.
    Class,
}

#[derive(Debug, Clone, PartialEq)]
pub struct Infix {
    pub associativity: Associativity,
    pub precedence: u8,
    pub function_name: Name,
    /// Where the `infix` declaration this came from was written.
    pub span: NodeSpan,
}

#[derive(Debug, Clone, PartialEq)]
pub struct UnionType {
    pub variables: Vec<Name>,
    pub variants: Vec<TypeConstructor>,
    /// Where the `type` declaration this came from was written.
    pub span: NodeSpan,
}

// TODO Once we have most of the pipeline built, revisit the decision of
// having Vec<Type> + Type instead of Type::Arrow(Box<Type>, Box<Type>)
// as it's essentially what a constructor is, a function from parameter
// to the resulting type.
// Later me: well, that's only true at the type level. The value also need
// to tag what variant it represent.
#[derive(Debug, Clone, PartialEq)]
pub struct TypeConstructor {
    /// Constructor name. eg. in `type A = B`, the name is `B`
    pub name: Name,
    /// The types of the parameters
    pub type_parameters: Vec<Type>,
    /// The type's name once constructed, qualified by the package and module that
    /// declared it — `Widget.Size` for a `type Size = …` written in `Widget`.
    ///
    /// Qualified for the same reason [`Type::Type`]'s head is (`AST-4`): a
    /// constructor travels into every module that imports it, and the type it
    /// builds has to stay the declaring module's type there. The `Type` this
    /// field is turned into at a use site — `Expression::from_parser`'s
    /// `TypeConstructor` arm — is built straight out of it, so the two agree by
    /// construction.
    pub tpe: QualName,
}

/// A canonical type.
///
/// # Why there is no span on this type, or on [`TypeConstructor`]
///
/// Every other canonical node this module builds carries a [`NodeSpan`] taken from
/// the parser node it came from. A `Type` deliberately does not.
///
/// The reason `ERR-3` recorded is that a `Type` does not always come from the module
/// being canonicalized: `Type::from_parser_type` resolves a name through the
/// `Environment`, which clones types straight out of the [`Interface`]s of the
/// modules this one imports, so the `Type` handed back may well have been *written
/// in a different file* — and a bare span on it would be read as a position in the
/// importing module's source. `ERR-5` settled that half: a [`SpanLabel`] can now
/// carry a file of its own, so "written in another file" is no longer the obstacle.
///
/// The other half is unfinished work, not an impossibility. `parser::Type` carries a
/// [`NodeSpan`] per node like every other parser node, and `Type::from_parser_type`
/// is the recursive walk over it — `tpe.span` is in hand at every level, and each
/// branch of an `Arrow` arrives as its own spanned `parser::Type`. Those spans are
/// discarded here by choice. Keeping them means a span field on every canonical
/// `Type` node, plus a decision about what a `Type` cloned out of an `Environment`
/// should then report — where it was written, or where it was used. Nobody has
/// written that.
///
/// What exists instead is coarser and enough for the diagnostics that exist: the
/// *declaration* a `Type` is the type of — [`Value`]'s own `span`, [`UnionType`]'s,
/// [`Infix`]'s — is what a diagnostic wants to underline ("defined here"), not a
/// position inside the type expression itself. [`Interface::values`] pairs each
/// value's `Type` with that declaration's [`NodeSpan`], and
/// [`Interface::source_span`] pairs it with the file, once [`Interface::file`] is
/// set. A type error still points at the whole declaration that failed rather than
/// the sub-expression that disagrees, which is `ERR-4`, a separate limit in the
/// typer's own `Term`/`Constraint` translation.
#[derive(Debug, Clone, PartialEq)]
pub enum Type {
    Variable(Name),
    /// A named type applied to its arguments, the name being the [`QualName`] of
    /// the declaration it resolved to.
    ///
    /// The module is part of the identity of the type, not decoration on it: a
    /// `type Size` in `Widget` and a `type Size` in `Gadget` are two types, and
    /// two values of them are interchangeable nowhere. Carrying only the
    /// spelling made them one value here, which is what `AST-4` closed. The
    /// package is part of it for the same reason: a local `Size` and a wrapped
    /// dependency's, reached as `AcmeWidgets.Size`, both declare `Size.Size`.
    ///
    /// The name is the *declaration's*, never the spelling that reached it.
    /// `import Widget as W` followed by `W.Size` records `Widget.Size`, the same
    /// rule [name resolution](../../docs/spec/name-resolution.md) states for
    /// values: an alias names a route to a declaration and not a second
    /// declaration. A dependency's namespace is a route too.
    Type(QualName, Vec<Type>),
    /// A [record type](../../docs/spec/records.md#the-type): each label, and the type
    /// of the field it names.
    ///
    /// A map rather than the list the source wrote, because [a record type is a set
    /// of fields](../../docs/spec/records.md#a-record-type-is-a-set-of-fields): `{ a :
    /// Int, b : Char }` and `{ b : Char, a : Int }` are one type, and are one value
    /// here. The map is ordered by label ([`Name`]'s `Ord`), so walking it is the
    /// label order two spellings of a type agree on. A label appears once:
    /// `Type::from_parser_type` reports a repeated one as [`Error::RepeatedLabel`]
    /// and builds no `Record`.
    Record(BTreeMap<Name, Type>),
    Arrow(Box<Type>, Box<Type>),
    /// A tuple type. Zelkova keeps Elm's restriction of two or three elements,
    /// which [`Tuple`] carries in its shape.
    Tuple(Tuple<Type>),
    /// [The unit type](../../docs/spec/types.md#the-unit-type), `()`.
    ///
    /// A form of its own rather than a [`Type::Type`] naming a declaration: `()` is
    /// syntax, declared nowhere and resolved through no environment, so no module can
    /// declare a type that shares its spelling and there is no name for a lookup to
    /// find. Contrast the [`scalars`], which are declared in `std/core` and known by
    /// the qualified name of that declaration.
    Unit,
    // Alias
}

impl Type {
    /// The one conversion in this module that reads a span and produces none.
    ///
    /// `parser::Type` carries a [`NodeSpan`] like every other parser node, and it is
    /// dropped here on purpose — see this type's documentation for why a canonical
    /// `Type` holds no span at all, and what `ERR-5` built instead.
    fn from_parser_type(env: &dyn Environment, tpe: &parser::Type) -> Result<Type, Error> {
        match &tpe.kind {
            parser::TypeKind::Unqualified(name, vars) => {
                let args = vars
                    .iter()
                    .map(|t| Type::from_parser_type(env, t))
                    .collect::<Result<Vec<_>, Error>>()?;

                match env.find_type(name) {
                    // `name` resolves to a declared type: `args` is what was
                    // written after it, and has to match the declaration's own
                    // arity (`BUG-17`) — nothing else here re-derives that check.
                    // The head is the *declaration's* qualified name, not the one
                    // written: `Lib.Option`, `Option` and an alias' `L.Option` are
                    // three spellings of one entry, and every one of them records
                    // the module that declared it.
                    Some(declared) if declared.arity() == args.len() => {
                        Ok(Type::Type(declared.name.clone(), args))
                    }
                    Some(declared) => Err(Error::TypeArityMismatch(
                        name.clone(),
                        declared.arity(),
                        args.len(),
                        tpe.span,
                    )),
                    // `name` resolves to nothing, so there is no type here to
                    // build one out of. The name is reported as written, dotted
                    // prefix and all: a written `W.Thing` says which *route* was
                    // written and not which module declared anything — under
                    // `import Widget as W` that half is an alias — so there is no
                    // module to attribute it to, and quoting the spelling back is
                    // what lets the reader find it in their own source.
                    None => Err(Error::TypeNotFound(name.clone(), tpe.span)),
                }
            }
            parser::TypeKind::Arrow(t1, t2) => Ok(Type::Arrow(
                Box::new(Type::from_parser_type(env, t1)?),
                Box::new(Type::from_parser_type(env, t2)?),
            )),
            parser::TypeKind::Variable(n) => Ok(Type::Variable(n.clone())),
            parser::TypeKind::Tuple(tuple) => Ok(Type::Tuple(
                tuple.try_map(|t| Type::from_parser_type(env, t))?,
            )),
            parser::TypeKind::Unit => Ok(Type::Unit),
            parser::TypeKind::Record(fields) => {
                repeated_labels(fields, RecordForm::Type)?;

                let fields = fields
                    .iter()
                    .map(|field| {
                        Ok((
                            field.label.clone(),
                            Type::from_parser_type(env, &field.value)?,
                        ))
                    })
                    .collect::<Result<BTreeMap<_, _>, Error>>()?;

                Ok(Type::Record(fields))
            }
        }
    }

    /// How many arguments a value of this type takes before its result is not a
    /// function: the length of its arrow spine. `Int -> Int -> Bool` is 2, `Int` is 0.
    pub fn arrow_count(&self) -> usize {
        match self {
            Type::Arrow(_, result) => 1 + result.arrow_count(),
            _ => 0,
        }
    }

    // TODO Write some tests
    fn to_linear_types(tpe: &Type) -> Vec<Type> {
        match tpe {
            Type::Arrow(a, b) => {
                let mut next = Type::to_linear_types(b);

                next.insert(0, *a.clone());

                next
            }
            _ => vec![tpe.clone()],
        }
    }
}

#[derive(Debug, Clone, PartialEq)]
pub enum Value {
    Value {
        name: Name,
        patterns: Vec<Pattern>,
        body: Expression,
        /// Where the declaration was written, annotation and body together.
        span: NodeSpan,
    },
    TypedValue {
        name: Name,
        patterns: Vec<(Pattern, Type)>,
        body: Expression,
        tpe: Type,
        /// The constraints the annotation wrote in front of `=>`, each resolved to its
        /// class, in the order written; empty for an annotation with no `=>`.
        ///
        /// A field beside `tpe` and not a case of [`Type`],
        /// which keeps a context out of every match over a type. Nothing needs one
        /// *inside* a type: a constraint stands only at the front of an annotation, and
        /// a [member signature carries
        /// none](../../docs/spec/type-classes.md#declaring-a-class). Always empty in a
        /// facade, whose context is [`Error::FacadeConstrained`] and is not resolved.
        context: Vec<Constraint>,
        /// True when the annotation was written `unsafe name : Type`.
        ///
        /// The word is only meaningful on a facade signature, where it declares a
        /// plain function in place of the effect a facade declares by default —
        /// see [Foreign interoperability](../../docs/spec/interop.md). Only a
        /// module whose `binding_foreign` is set can carry it: [`canonicalize`]
        /// reports [`Error::UnsafeOutsideFacade`] for one written anywhere else,
        /// so this is `false` on every value of an ordinary module.
        marked_unsafe: bool,
        /// Where the declaration was written, annotation and body together.
        span: NodeSpan,
        /// Where the `name : Type` annotation alone was written.
        ///
        /// [`Type`] itself carries no span — it may have been cloned out of another
        /// module's `Interface` — so this is the only thing that can answer "where
        /// was the expected type declared". A type error uses it for the secondary
        /// label that says the annotation is what the body is being held to.
        annotation_span: NodeSpan,
    },
}

impl Value {
    /// Where this declaration was written, whichever variant it is.
    ///
    /// The typer falls back to this when a type error has no finer position of its
    /// own — see `typer::Error::labels`.
    pub fn span(&self) -> NodeSpan {
        match self {
            Value::Value { span, .. } | Value::TypedValue { span, .. } => *span,
        }
    }

    /// How many parameters this declaration was written with.
    ///
    /// This is the count of patterns on the left of the `=`, and deliberately not the
    /// number of arrows in the declaration's type: `f : Int -> Int -> Int` written `f a =
    /// add a` has arity 1, and returns a function for the second argument.
    ///
    /// The rule lives here rather than at any of its readers because they feed fields a
    /// backend reads together, from different phases. `typer`'s `Translation` uses it as
    /// the callee's arity at every call site naming this declaration, which is what
    /// decides [`ir::Saturation`](crate::ir::Saturation); `ir::build` uses it as
    /// [`ir::Declaration::arity`](crate::ir::Declaration::arity), the count a
    /// direct call has to supply; and [`Module::to_interface`] records it, through
    /// [`Module::emitted_arity`], for a module that imports the declaration. Copies that
    /// drifted apart would mark a call site saturated at a count the emitted function
    /// does not take. A facade signature has no patterns to count, and
    /// [`Module::emitted_arity`] reads its arrows instead.
    pub fn arity(&self) -> usize {
        // Two arms rather than an or-pattern: a `TypedValue`'s patterns each carry the
        // type the annotation gave them, so the two fields are different types.
        match self {
            Value::Value { patterns, .. } => patterns.len(),
            Value::TypedValue { patterns, .. } => patterns.len(),
        }
    }

    /// Whether the declaration's parameters or body hold a hole, an
    /// [`ExpressionKind::Hole`] or a [`PatternKind::Hole`] — a name that did not resolve.
    ///
    /// A hole is made only where the error for it was raised, and that error is either
    /// reported or dropped in an [incomplete](Module::incomplete) scope, where the failure
    /// that made the scope incomplete stands in its place
    /// ([`DEC-23` decision 3](../../../docs/decisions/dec-23.md)). So a declaration for which this
    /// is true always has an error standing behind it, which is what
    /// [`ir::Unchecked::reported`](crate::ir::Unchecked::reported) asks of an entry.
    /// A facade signature has no body, and the body of a `TypedValue` is read the same way
    /// a `Value`'s is.
    pub fn holds_hole(&self) -> bool {
        match self {
            Value::Value { patterns, body, .. } => {
                patterns.iter().any(pattern_holds_hole) || expression_holds_hole(body)
            }
            Value::TypedValue { patterns, body, .. } => {
                patterns
                    .iter()
                    .any(|(pattern, _)| pattern_holds_hole(pattern))
                    || expression_holds_hole(body)
            }
        }
    }
}

/// Whether `expr` is a hole or holds one in any subexpression or `case` pattern. The
/// walk is [`collect_top_level_refs`]'s, looking for a different kind.
fn expression_holds_hole(expr: &Expression) -> bool {
    match &expr.kind {
        ExpressionKind::Hole => true,
        ExpressionKind::VarTopLevel(_)
        | ExpressionKind::VarLocal(_)
        | ExpressionKind::VarKernel(_)
        | ExpressionKind::VarForeign(_, _, _)
        | ExpressionKind::VarConstructor(_, _)
        | ExpressionKind::Char(_)
        | ExpressionKind::String(_)
        | ExpressionKind::Int(_)
        | ExpressionKind::Float(_)
        | ExpressionKind::Unit
        // A label is not a name, so it never resolves and is never a hole.
        | ExpressionKind::Accessor(_, _) => false,
        ExpressionKind::Access(record, _, _) => expression_holds_hole(record),
        ExpressionKind::Apply(a, b) => expression_holds_hole(a) || expression_holds_hole(b),
        ExpressionKind::If(cond, then, els) => {
            expression_holds_hole(cond) || expression_holds_hole(then) || expression_holds_hole(els)
        }
        ExpressionKind::Case(scrutinee, branches) => {
            expression_holds_hole(scrutinee)
                || branches.iter().any(|branch| {
                    pattern_holds_hole(&branch.pattern) || expression_holds_hole(&branch.expression)
                })
        }
        ExpressionKind::Tuple(tuple) => tuple.iter().any(expression_holds_hole),
        ExpressionKind::Record(fields) => fields
            .iter()
            .any(|field| expression_holds_hole(&field.value)),
        ExpressionKind::Update(record, fields) => {
            expression_holds_hole(record)
                || fields
                    .iter()
                    .any(|field| expression_holds_hole(&field.value))
        }
    }
}

/// Whether `pattern` is a hole or holds one in any argument or element.
fn pattern_holds_hole(pattern: &Pattern) -> bool {
    match &pattern.kind {
        PatternKind::Hole(_) => true,
        PatternKind::Constructor { args, .. } => args.iter().any(pattern_holds_hole),
        PatternKind::Tuple(tuple) => tuple.iter().any(pattern_holds_hole),
        PatternKind::Record(fields) => fields
            .iter()
            .any(|field| pattern_holds_hole(&field.pattern)),
        PatternKind::Anything
        | PatternKind::Variable(_)
        | PatternKind::Int(_)
        | PatternKind::Float(_)
        | PatternKind::Char(_)
        | PatternKind::String(_)
        | PatternKind::Unit => false,
    }
}

/// A canonical pattern, and where it was written.
///
/// Same shape as [`parser::Pattern`] — a [`NodeSpan`] beside a kind — and for the
/// same reason: the children stay plain `Pattern`s, so a reader matches `&p.kind`.
#[derive(Debug, Clone, PartialEq)]
pub struct Pattern {
    pub span: NodeSpan,
    pub kind: PatternKind,
}

#[derive(Debug, Clone, PartialEq)]
pub enum PatternKind {
    Anything,
    Variable(Name), // TODO Name or QualName ?
    Int(i64),
    Float(f64),
    Char(char),
    String(String),
    /// A tuple pattern. Zelkova keeps Elm's restriction of two or three
    /// elements, which [`Tuple`] carries in its shape.
    Tuple(Tuple<Pattern>),
    /// The unit pattern, `()`: it matches the one value of the unit type and binds
    /// nothing.
    Unit,

    Constructor {
        ctor: TypeConstructor,
        args: Vec<Pattern>,
    },
    /// A constructor pattern whose constructor did not resolve, with the patterns written
    /// as its arguments. The error saying so has been reported, or dropped in an
    /// [incomplete](Module::incomplete) scope, and the declaration is kept ([`DEC-23`
    /// decision
    /// 6](../../../docs/decisions/dec-23.md#6--an-unresolved-name-inside-a-sound-body-is-a-typed-hole)).
    ///
    /// The arguments are kept so that the names they bind are still in scope in the
    /// branch or the body the pattern governs, and a use of one there is not reported as a
    /// second missing name.
    Hole(Vec<Pattern>),
    /// A [record pattern](../../docs/spec/records.md#record-patterns), `{ label =
    /// pattern, … }`: the fields it names, each with the pattern its value is matched
    /// against, in the order they were written. The `{ label }` shorthand is not a form
    /// of its own: the grammar desugared it to `label = label`.
    ///
    /// The entries name a **subset** of the record's fields, so this is not the whole
    /// field set a [`Type::Record`] is, and it is not keyed by label the way that one
    /// is. No label appears twice — `Pattern::from_parser` reports a repeated one as
    /// [`Error::RepeatedLabel`] — and what the pattern matches does not depend on the
    /// order of its entries. They are kept as the source wrote them, as a tuple's
    /// elements are, and `ScopedEnvironment::expose_pattern` walks them in that order.
    /// Each entry keeps its label's span, which is where a diagnostic about that field
    /// points.
    ///
    /// Refutable exactly when one of its entries' patterns is (`{ x }` cannot fail,
    /// `{ x = 0 }` can). Nothing here records that, and nothing may read a record
    /// pattern as irrefutable for being a record.
    Record(Vec<PatternField>),
}

/// One entry of a [record pattern](PatternKind::Record): the label it names, where the
/// label alone was written, and the pattern that field's value is matched against.
#[derive(Debug, Clone, PartialEq)]
pub struct PatternField {
    pub label: Name,
    /// Where the label alone was written; the pattern carries its own span. For the
    /// `{ label }` shorthand the two are the same text.
    pub label_span: NodeSpan,
    pub pattern: Pattern,
}

impl Pattern {
    /// A pattern canonicalized from source, keeping the parser node's position.
    pub fn new(span: NodeSpan, kind: PatternKind) -> Pattern {
        Pattern { span, kind }
    }

    /// A pattern with no position — hand-built by a test. See [`NodeSpan`].
    pub fn bare(kind: PatternKind) -> Pattern {
        Pattern {
            span: NodeSpan::none(),
            kind,
        }
    }

    /// The canonical form of `p`, or the first error that kept it from having one.
    ///
    /// A constructor that does not resolve is not such an error: its `VariantNotFound` is
    /// pushed onto `unresolved` and the pattern becomes a [`PatternKind::Hole`] holding its
    /// arguments, canonicalized as a resolved constructor's are.
    fn from_parser(
        p: &parser::Pattern,
        env: &dyn Environment,
        unresolved: &mut Vec<Error>,
    ) -> Result<Pattern, Error> {
        let kind = match &p.kind {
            parser::PatternKind::Anything => PatternKind::Anything,
            parser::PatternKind::Variable(name) => PatternKind::Variable(name.clone()),
            parser::PatternKind::Literal(parser::Literal::Int(i)) => PatternKind::Int(*i),
            parser::PatternKind::Literal(parser::Literal::Float(f)) => PatternKind::Float(*f),
            parser::PatternKind::Literal(parser::Literal::Char(c)) => PatternKind::Char(*c),
            parser::PatternKind::Literal(parser::Literal::String(s)) => {
                PatternKind::String(s.clone())
            }
            parser::PatternKind::Tuple(tuple) => {
                PatternKind::Tuple(tuple.try_map(|p| Pattern::from_parser(p, env, unresolved))?)
            }
            parser::PatternKind::Unit => PatternKind::Unit,
            parser::PatternKind::Constructor(name, args) => {
                // `p.span` covers the constructor and its arguments, which is the
                // text a "no such constructor" caret should sit under.
                let ctor = match env.find_type_constructor(name) {
                    Some(ctor) => Some(ctor.clone()),
                    None => {
                        let suggestion =
                            suggest_name(name, env.type_constructor_names().into_iter());
                        unresolved.push(Error::VariantNotFound(
                            env.module_name().qualify_name(name),
                            p.span,
                            suggestion,
                        ));
                        None
                    }
                };

                let args = args
                    .iter()
                    .map(|p| Pattern::from_parser(p, env, unresolved))
                    .collect::<Result<Vec<_>, Error>>()?;

                match ctor {
                    Some(ctor) => PatternKind::Constructor { ctor, args },
                    None => PatternKind::Hole(args),
                }
            }
            // Every entry's pattern is canonicalized before the labels are compared, as a
            // record's fields are in `Field::from_parser`, so a constructor that does not
            // resolve in one is pushed onto `unresolved` whether or not a label repeats.
            parser::PatternKind::Record(fields) => {
                let entries = fields
                    .iter()
                    .map(|field| {
                        Ok(PatternField {
                            label: field.label.clone(),
                            label_span: field.label_span,
                            pattern: Pattern::from_parser(&field.value, env, unresolved)?,
                        })
                    })
                    .collect::<Result<Vec<_>, Error>>()?;

                repeated_labels(fields, RecordForm::Pattern)?;

                PatternKind::Record(entries)
            }
        };

        Ok(Pattern::new(p.span, kind))
    }
}

/// A canonical expression, and where it was written.
///
/// Same shape as [`parser::Expression`] — a [`NodeSpan`] beside a kind — and for the
/// same reason: the children stay `Box<Expression>`, so a reader matches `&e.kind`.
#[derive(Debug, Clone, PartialEq)]
pub struct Expression {
    pub span: NodeSpan,
    pub kind: ExpressionKind,
}

// TODO Find a way to detect recursive functions (even indirect recursivity,
// eg. `a` calls `b` calls `a`)
/// Expression is an optimized version for checks and caches.
///
/// Elm declare those expressions:
/// ```haskell
/// data Expr_
///   = VarLocal Name
///   | VarTopLevel ModuleName.Canonical Name
///   | VarKernel Name Name
///   | VarForeign ModuleName.Canonical Name Annotation
///   | VarCtor CtorOpts ModuleName.Canonical Name Index.ZeroBased Annotation
///   | VarDebug ModuleName.Canonical Name Annotation
///   | VarOperator Name ModuleName.Canonical Name Annotation -- CACHE real name for optimization
///   | Chr ES.String
///   | Str ES.String
///   | Int Int
///   | Float EF.Float
///   | List [Expr]
///   | Negate Expr
///   | Binop Name ModuleName.Canonical Name Annotation Expr Expr -- CACHE real name for optimization
///   | Lambda [Pattern] Expr
///   | Call Expr [Expr]
///   | If [(Expr, Expr)] Expr
///   | Let Def Expr
///   | LetRec [Def] Expr
///   | LetDestruct Pattern Expr Expr
///   | Case Expr [CaseBranch]
///   | Accessor Name
///   | Access Expr (A.Located Name)
///   | Update Name Expr (Map.Map Name FieldUpdate)
///   | Record (Map.Map Name Expr)
///   | Unit
///   | Tuple Expr Expr (Maybe Expr)
/// ```
#[derive(Debug, Clone, PartialEq)]
pub enum ExpressionKind {
    VarLocal(Name),
    VarTopLevel(QualName),
    VarKernel(QualName),
    /// A value another module declares, named by that module, beside the package that
    /// declares it. The package is what a backend builds the import path from: a
    /// module's name is unique within its package and not across a build, and the
    /// output keeps one directory per package
    /// ([`DEC-18` decision 5](../../docs/decisions/dec-18.md#5--output-is-written-per-package-beside-the-root-manifest)).
    VarForeign(QualName, PackageName, Type),
    /// A union constructor, named by the package and module that declared its union
    /// whichever module the reference is written in. The [`QualName`] carries the
    /// package: `AcmeWidgets.Size.Small` and a local `Size.Small` are two constructors.
    VarConstructor(QualName, Type),
    Char(char),
    String(String),
    Int(i64),
    Float(f64),
    // List
    // Lambda
    Apply(Box<Expression>, Box<Expression>),
    If(Box<Expression>, Box<Expression>, Box<Expression>),
    // Let
    // LetRec
    // LetDestruct (eg. `(a,b) = someTuple`)
    Case(Box<Expression>, Vec<CaseBranch>),
    /// An [accessor](../../docs/spec/records.md#the-accessor), `.name`, the function
    /// reading that field: the label, and where the label alone was written.
    ///
    /// The label names no declaration, so nothing about it is resolved here: [labels
    /// are not values](../../docs/spec/records.md#labels-are-not-values), and which
    /// record the label belongs to is decided by the type the accessor is read against.
    Accessor(Name, NodeSpan),
    /// A [field access](../../docs/spec/records.md#reading-a-field), `r.name`: the
    /// record, the label, and where the label alone was written. The label is not
    /// resolved here either, for the reason an [`Accessor`](ExpressionKind::Accessor)'s
    /// is not.
    Access(Box<Expression>, Name, NodeSpan),
    /// A [record](../../docs/spec/records.md#building-a-record), `{ label = expr, … }`,
    /// its fields in the order they were written.
    ///
    /// A list and not a map, as [`Type::Record`] is: each field is a subexpression,
    /// and [subexpressions are evaluated left to
    /// right](../../docs/spec/evaluation-semantics.md#order-of-evaluation), so `{ b = f
    /// x, a = g y }` calls `f` first and a backend has to be able to see that. Only the
    /// set of labels is order-independent, and no label appears twice:
    /// `Expression::from_parser` reports a repeated one as [`Error::RepeatedLabel`].
    Record(Vec<Field>),
    /// An [update](../../docs/spec/records.md#updating-a-record), `{ expr | label =
    /// expr, … }`: the record being updated, and the fields replaced in it in the order
    /// they were written, for the reason a [`Record`](ExpressionKind::Record)'s are.
    Update(Box<Expression>, Vec<Field>),
    /// The unit value, `()`.
    Unit,
    /// A tuple expression. Zelkova keeps Elm's restriction of two or three
    /// elements, which [`Tuple`] carries in its shape.
    Tuple(Tuple<Expression>),
    /// A value or a constructor that did not resolve, inside a body that otherwise
    /// canonicalized. The error saying so has been reported, or dropped in an
    /// [incomplete](Module::incomplete) scope, and the declaration is kept, so the rest of
    /// its body is still checked ([`DEC-23` decision
    /// 6](../../../docs/decisions/dec-23.md#6--an-unresolved-name-inside-a-sound-body-is-a-typed-hole)).
    Hole,
}

/// One field of a [record](ExpressionKind::Record) or an
/// [update](ExpressionKind::Update): a label, where the label was written, and the
/// expression it was given.
#[derive(Debug, Clone, PartialEq)]
pub struct Field {
    pub label: Name,
    /// Where the label alone was written; the value carries its own span.
    pub label_span: NodeSpan,
    pub value: Expression,
}

impl Field {
    /// The canonical form of `fields`, a record's or an update's, in the order they
    /// were written. Every value is canonicalized before the labels are compared, so a
    /// name that does not resolve in one is pushed onto `unresolved` whether or not a
    /// label is repeated; a repeated label is then the error returned.
    fn from_parser(
        fields: &[parser::Field<parser::Expression>],
        form: RecordForm,
        env: &dyn Environment,
        unresolved: &mut Vec<Error>,
    ) -> Result<Vec<Field>, Error> {
        let canonical = fields
            .iter()
            .map(|field| {
                Ok(Field {
                    label: field.label.clone(),
                    label_span: field.label_span,
                    value: Expression::from_parser(&field.value, env, unresolved)?,
                })
            })
            .collect::<Result<Vec<_>, Error>>()?;

        repeated_labels(fields, form)?;

        Ok(canonical)
    }
}

/// Which of the four record forms a [`Error::RepeatedLabel`] was found in.
#[derive(Debug, PartialEq, Clone, Copy)]
pub enum RecordForm {
    /// A record type, `{ label : Type, … }`.
    Type,
    /// A record, `{ label = expr, … }`.
    Record,
    /// An update, `{ expr | label = expr, … }`.
    Update,
    /// A record pattern, `{ label = pattern, … }`, the `{ label }` shorthand included.
    Pattern,
}

/// Every field of `fields` whose label an earlier field already has, each as an
/// [`Error::RepeatedLabel`] at its own label and naming the first field's: `Ok` when
/// there is none, the one error when there is one, and [`Error::Many`] of them when
/// there are several. A label written three times is two errors, both naming the
/// first.
fn repeated_labels<T>(fields: &[parser::Field<T>], form: RecordForm) -> Result<(), Error> {
    let mut first: HashMap<&Name, NodeSpan> = HashMap::new();
    let mut errors = vec![];

    for field in fields {
        match first.get(&field.label) {
            Some(earlier) => errors.push(Error::RepeatedLabel(
                field.label.clone(),
                form,
                field.label_span,
                *earlier,
            )),
            None => {
                first.insert(&field.label, field.label_span);
            }
        }
    }

    match errors.len() {
        0 => Ok(()),
        1 => Err(errors.remove(0)),
        _ => Err(Error::Many(errors)),
    }
}

impl Expression {
    /// An expression canonicalized from source, keeping the parser node's position.
    pub fn new(span: NodeSpan, kind: ExpressionKind) -> Expression {
        Expression { span, kind }
    }

    /// An expression with no position: hand-built by a test, or synthesised by the
    /// compiler with nothing in the user's text behind it. See [`NodeSpan`].
    pub fn bare(kind: ExpressionKind) -> Expression {
        Expression {
            span: NodeSpan::none(),
            kind,
        }
    }

    /// The canonical form of `e`, or the first error that kept it from having one.
    ///
    /// A value or a constructor that does not resolve is not such an error: its
    /// `VariableNotFound` or `VariantNotFound` is pushed onto `unresolved` and the node
    /// becomes an [`ExpressionKind::Hole`]. Every other failure is returned, among them an
    /// ambiguous name, which did resolve, and an operator that does not resolve or an infix
    /// chain that cannot be associated, either of which leaves the chain with no shape to
    /// put a hole in.
    fn from_parser(
        e: &parser::Expression,
        env: &dyn Environment,
        unresolved: &mut Vec<Error>,
    ) -> Result<Expression, Error> {
        // Every arm builds a kind and every kind gets `e.span`, so a name the
        // environment cannot resolve is underlined where it was written rather than
        // somewhere up the tree.
        let kind = match &e.kind {
            parser::ExpressionKind::Lit(parser::Literal::Int(i)) => ExpressionKind::Int(*i),
            parser::ExpressionKind::Lit(parser::Literal::Float(f)) => ExpressionKind::Float(*f),
            parser::ExpressionKind::Lit(parser::Literal::Char(c)) => ExpressionKind::Char(*c),
            parser::ExpressionKind::Lit(parser::Literal::String(s)) => {
                ExpressionKind::String(s.clone())
            }
            parser::ExpressionKind::Variable(name) => {
                let Some(found) = env.find_value(name) else {
                    let suggestion = suggest_name(name, env.value_names().into_iter());
                    unresolved.push(Error::VariableNotFound(
                        env.module_name().qualify_name(name),
                        e.span,
                        suggestion,
                    ));
                    return Ok(Expression::new(e.span, ExpressionKind::Hole));
                };

                match found {
                    ValueType::Local => ExpressionKind::VarLocal(name.clone()),
                    ValueType::TopLevel => {
                        ExpressionKind::VarTopLevel(env.module_name().qualify_name(name))
                    }
                    // Named by the package and module that declared the value, `m`. The
                    // written spelling is bare for an exposed value and carries a module
                    // or an alias for a qualified one (`Js.Basics.add`), and only its
                    // last segment is the value's own name.
                    ValueType::Foreign(m, _source, tpe, _origin) => {
                        let declared = name.last_segment();
                        ExpressionKind::VarForeign(
                            m.qualify_name(&declared),
                            m.package().clone(),
                            tpe.clone(),
                        )
                    }
                    ValueType::Foreigns(candidates) => {
                        return Err(Error::AmbiguousVariables(
                            name.clone(),
                            candidates.clone(),
                            e.span,
                        ))
                    }
                }
            }
            parser::ExpressionKind::TypeConstructor(name) => {
                let Some(ctor) = env.find_type_constructor(name) else {
                    let suggestion = suggest_name(name, env.type_constructor_names().into_iter());
                    unresolved.push(Error::VariantNotFound(
                        env.module_name().qualify_name(name),
                        e.span,
                        suggestion,
                    ));
                    return Ok(Expression::new(e.span, ExpressionKind::Hole));
                };

                let tpe = if ctor.type_parameters.is_empty() {
                    Type::Type(ctor.tpe.clone(), vec![])
                } else {
                    // TODO Rework that part. ctor.types is only for the type parameters of the constructor, not for the overall type.
                    let mut iter = ctor.type_parameters.iter().rev();
                    let first = iter.next().unwrap().clone();

                    // TODO tests this, 99.999% I'm wrong about it (like everytime I try to implement arrows, plus
                    // the foldr in this particular case)
                    let tpe = iter.fold(first, |acc, t| {
                        Type::Arrow(Box::new(t.clone()), Box::new(acc))
                    });

                    Type::Arrow(
                        Box::new(Type::Type(ctor.tpe.clone(), vec![])),
                        Box::new(tpe),
                    )
                };

                // Named by the package and module that declared the union, the way
                // `VarForeign` is named by the ones that declared the value — not by the
                // spelling the source wrote, which is bare for an exposed constructor and
                // carries the importer's alias or a dependency's namespace for a
                // qualified one.
                let name = ctor.tpe.sibling(&ctor.name);

                ExpressionKind::VarConstructor(name, tpe)
            }
            parser::ExpressionKind::Application(a, b) => {
                let a = Expression::from_parser(a, env, unresolved)?;
                let b = Expression::from_parser(b, env, unresolved)?;

                ExpressionKind::Apply(Box::new(a), Box::new(b))
            }
            parser::ExpressionKind::InfixChain(first, rest) => {
                let first = Expression::from_parser(first, env, unresolved)?;

                let rest = rest
                    .iter()
                    .map(|(op_name, op_span, operand)| {
                        let op = resolve_infix_operator(op_name, *op_span, env)?;
                        let operand = Expression::from_parser(operand, env, unresolved)?;
                        Ok((op, operand))
                    })
                    .collect::<Result<Vec<_>, Error>>()?;

                let mut rest = rest.into_iter().peekable();
                let reassociated = reassociate_infix_chain(first, &mut rest, 0)?;

                reassociated.kind
            }
            parser::ExpressionKind::Tuple(tuple) => ExpressionKind::Tuple(
                tuple.try_map(|e| Expression::from_parser(e, env, unresolved))?,
            ),
            parser::ExpressionKind::Unit => ExpressionKind::Unit,
            parser::ExpressionKind::Case(expr, branches) => {
                let expr = Expression::from_parser(expr, env, unresolved)?;

                let b = branches.iter().map::<Result<CaseBranch, Error>, _>(|cb| {
                    let pattern = Pattern::from_parser(&cb.pattern, env, unresolved)?;
                    let mut scoped = env.new_scope();

                    scoped.expose_pattern(&pattern);

                    let expression = Expression::from_parser(&cb.expression, &scoped, unresolved)?;

                    Ok(CaseBranch {
                        pattern,
                        expression,
                        span: cb.span,
                    })
                });

                let branches = collect_accumulate(b)?;

                ExpressionKind::Case(Box::new(expr), branches)
            }
            parser::ExpressionKind::If(cond, then, els) => {
                let cond = Expression::from_parser(cond, env, unresolved)?;
                let then = Expression::from_parser(then, env, unresolved)?;
                let els = Expression::from_parser(els, env, unresolved)?;

                ExpressionKind::If(Box::new(cond), Box::new(then), Box::new(els))
            }
            parser::ExpressionKind::Record(fields) => ExpressionKind::Record(Field::from_parser(
                fields,
                RecordForm::Record,
                env,
                unresolved,
            )?),
            // The record being updated is canonicalized ahead of its fields, the order
            // it is written and evaluated in.
            parser::ExpressionKind::Update(record, fields) => {
                let record = Expression::from_parser(record, env, unresolved)?;
                let fields = Field::from_parser(fields, RecordForm::Update, env, unresolved)?;

                ExpressionKind::Update(Box::new(record), fields)
            }
            parser::ExpressionKind::Access(record, label, label_span) => ExpressionKind::Access(
                Box::new(Expression::from_parser(record, env, unresolved)?),
                label.clone(),
                *label_span,
            ),
            parser::ExpressionKind::Accessor(label, label_span) => {
                ExpressionKind::Accessor(label.clone(), *label_span)
            }
        };

        Ok(Expression::new(e.span, kind))
    }
}

/// One operator of an `ExpressionKind::InfixChain`, resolved against the infix
/// environment: its own `Infix` (precedence, associativity, and where it was
/// declared) alongside the canonical `Expression` it resolves to as a value —
/// a reference to the function its `infix` declaration names, qualified with the
/// module that wrote that declaration. `reassociate_infix_chain` consults `infix`
/// to decide how to nest, and `span` and `expr` to build the invented
/// `Application` nodes.
struct ResolvedInfixOp {
    name: Name,
    /// Where the operator itself was written — not its `infix` declaration.
    span: NodeSpan,
    expr: Expression,
    infix: Infix,
    /// Where the `infix` declaration was written, and in which module's file —
    /// the operator may well have been declared by an imported module, in which
    /// case `infix.span` is a byte range in *that* module's source. See
    /// [`InfixDeclaration`].
    declaration: InfixDeclaration,
}

/// Resolves one operator of an `InfixChain` into the function its `infix`
/// declaration names, plus the `Infix` re-association needs.
///
/// The `infixes` map is the whole of an operator's scope: nothing else can hold
/// a key spelled like one, since a function's own name always comes from
/// `VarIdent`, a distinct token from `Op`. So `find_infix` failing is exactly
/// "no operator by that name is in scope", and gets the `VariableNotFound` a
/// reader would expect for a name they wrote and nothing declares.
///
/// The function behind the operator is resolved from the entry
/// ([`InfixFunction`]) rather than looked up in the scope the operator is *used*
/// in. An operator has no qualified spelling, so naming it in an `exposing` list
/// is the only way to reach one across a module boundary, and whether the
/// exporting module's backing function is separately in scope is neither the
/// importer's choice nor visible to them. The resulting `VarTopLevel`/`VarForeign`
/// is qualified with the module that wrote the `infix` declaration and names the
/// function, not the operator symbol, so it matches the binding a later phase
/// looks it up against.
fn resolve_infix_operator(
    name: &Name,
    span: NodeSpan,
    env: &dyn Environment,
) -> Result<ResolvedInfixOp, Error> {
    let entry = env.find_infix(name).cloned().ok_or_else(|| {
        let suggestion = suggest_name(name, env.value_names().into_iter());
        Error::VariableNotFound(env.module_name().qualify_name(name), span, suggestion)
    })?;

    let function_name = &entry.infix.function_name;
    let kind = match &entry.function {
        InfixFunction::Local => {
            ExpressionKind::VarTopLevel(env.module_name().qualify_name(function_name))
        }
        InfixFunction::Imported(module, tpe) => ExpressionKind::VarForeign(
            module.qualify_name(function_name),
            module.package().clone(),
            tpe.clone(),
        ),
        // The exporting module declared the backing function without an
        // annotation, so its interface carries no type for it. The name that
        // failed to resolve is the function's, and that is what is reported —
        // the operator is in scope, and saying otherwise would send the reader
        // to check their own `import` line.
        InfixFunction::ImportedUntyped(module) => {
            return Err(Error::VariableNotFound(
                module.qualify_name(function_name),
                span,
                None,
            ))
        }
    };

    Ok(ResolvedInfixOp {
        name: name.clone(),
        span,
        expr: Expression::new(span, kind),
        infix: entry.infix,
        declaration: entry.declaration,
    })
}

/// Re-associates a flat run of operator applications into a tree of
/// `Application` nodes, in one pass over the operators — no operator or operand
/// is visited twice — using precedence climbing (a standard algorithm; see e.g.
/// https://en.wikipedia.org/wiki/Operator-precedence_parser#Precedence_climbing_method).
///
/// `min_prec` is the lowest precedence this call is willing to fold into `lhs`;
/// the outer, top-level call passes 0, admitting every operator. A recursive
/// call raises it to bind only the tighter operators that belong on the right
/// of the operator being folded — `op.infix.precedence + 1` for strictly higher
/// precedence, or `op.infix.precedence` itself when the next operator ties and
/// both associate right, which is what lets a right-associative run keep
/// folding at the same level (`a <| b <| c` → `a <| (b <| c)`).
///
/// Two adjacent operators of equal precedence are rejected rather than guessed
/// at unless they agree — both `left` (fold `lhs`, the usual case) or both
/// `right` (recurse into `rhs`). Anything else — a `left` against a `right`, or
/// either against an `infix non` operator, including one against itself — is
/// `Error::AmbiguousOperatorPrecedence`: nothing here says which one should
/// bind first, and guessing would silently pick a grouping the user did not
/// write.
fn reassociate_infix_chain(
    mut lhs: Expression,
    rest: &mut std::iter::Peekable<impl Iterator<Item = (ResolvedInfixOp, Expression)>>,
    min_prec: u8,
) -> Result<Expression, Error> {
    while let Some((op, mut rhs)) = rest.next_if(|(op, _)| op.infix.precedence >= min_prec) {
        loop {
            let next_min = match rest.peek() {
                None => None,
                Some((next_op, _)) => {
                    if next_op.infix.precedence > op.infix.precedence {
                        Some(op.infix.precedence + 1)
                    } else if next_op.infix.precedence == op.infix.precedence {
                        match (op.infix.associativity, next_op.infix.associativity) {
                            (Associativity::Left, Associativity::Left) => None,
                            (Associativity::Right, Associativity::Right) => {
                                Some(op.infix.precedence)
                            }
                            _ => {
                                return Err(Error::AmbiguousOperatorPrecedence(
                                    AmbiguousOperator::new(&op),
                                    AmbiguousOperator::new(next_op),
                                    op.span.merge(next_op.span),
                                ))
                            }
                        }
                    } else {
                        None
                    }
                }
            };

            match next_min {
                Some(min) => rhs = reassociate_infix_chain(rhs, rest, min)?,
                None => break,
            }
        }

        lhs = apply_infix(op, lhs, rhs);
    }

    Ok(lhs)
}

/// Builds the two `Application` nodes one step of infix re-association adds,
/// following the same span convention the grammar's right-recursive rewrite
/// used before this: the partial application of the operator to `lhs` — a node
/// with nothing in the user's text of its own — takes the operator's own span,
/// and the outer application, which stands for `lhs op rhs` as the user wrote
/// it, spans from wherever `lhs` starts to wherever `rhs` ends.
fn apply_infix(op: ResolvedInfixOp, lhs: Expression, rhs: Expression) -> Expression {
    let span = lhs.span.merge(rhs.span);

    let partial = Expression::new(
        op.span,
        ExpressionKind::Apply(Box::new(op.expr), Box::new(lhs)),
    );

    Expression::new(
        span,
        ExpressionKind::Apply(Box::new(partial), Box::new(rhs)),
    )
}

/// One side of an [`Error::AmbiguousOperatorPrecedence`]: the operator as the user
/// spelled it, how its `infix` declaration said it associates, and where that
/// declaration was written.
///
/// `associativity` is carried rather than re-derived because the message depends on
/// it — an `infix non` operator does not chain at all, where a `left` against a
/// `right` is a choice the user can make with parentheses — and the error outlives
/// the environment the declaration was looked up in.
#[derive(Debug)]
pub struct AmbiguousOperator {
    pub name: Name,
    pub associativity: Associativity,
    pub declaration: InfixDeclaration,
}

impl AmbiguousOperator {
    fn new(op: &ResolvedInfixOp) -> Self {
        AmbiguousOperator {
            name: op.name.clone(),
            associativity: op.infix.associativity,
            declaration: op.declaration,
        }
    }

    fn is_non_associative(&self) -> bool {
        self.associativity == Associativity::None
    }
}

#[derive(Debug, Clone, PartialEq)]
pub struct CaseBranch {
    pub pattern: Pattern,
    pub expression: Expression,
    /// The whole branch, pattern and expression together.
    pub span: NodeSpan,
}

// end AST

/// Everything canonicalization can reject.
///
/// # Why only some variants carry a span
///
/// A variant carries a [`NodeSpan`] when its construction site has one in hand — it
/// is looking at a `parser::Import`, `parser::Infix`, `parser::UnionType`,
/// `parser::Function` or `parser::Exposed`, all of which the grammar gives a span.
/// Those are the variants a diagnostic can put a caret under, and today that is every
/// variant below except three: the two group variants, `EnvironmentErrors` and
/// `Many`, have no position of their own and flatten their members' labels instead;
/// and `InvalidTupleSize` carries none for an unrelated reason — see its own doc
/// comment. Writing `NodeSpan::none()` into a variant that lacks a real position
/// would say "this error has a position we happen not to know", which is a lie;
/// leaving the field off says "this error has nowhere to point", which is true, and
/// the reporter renders it as message-plus-notes with no caret.
#[derive(Debug)]
pub enum Error {
    /// A name in the `module … exposing (…)` header that nothing in the module
    /// declares, and where that name was written (`ERR-9`).
    ExportNotFound(Name, ExportType, NodeSpan),
    /// A value exposed by this module — named explicitly in its `exposing` list,
    /// or implicitly by `exposing (..)` — whose declaration carries no type
    /// annotation (`SPEC-5`: an exposed declaration must be annotated).
    ///
    /// The first [`NodeSpan`] is where the `exposing` list names it — a real
    /// position for an explicit list, `NodeSpan::none()` for `exposing (..)`,
    /// which names nothing individually and so has no per-value span to point
    /// at (`parser::Exposing::Open` carries none at all). The second is the
    /// declaration's own span, always real: `labels()` falls back to it as the
    /// primary label when the first is absent, rather than pointing nowhere.
    ExportedValueNotAnnotated(Name, NodeSpan, NodeSpan),
    EnvironmentErrors(Vec<EnvError>),
    /// (infix, function), and where the `infix` declaration was written
    InfixReferenceInvalidValue(Name, Name, NodeSpan),
    /// Infix re-association (`reassociate_infix_chain`) found two adjacent
    /// operators of equal precedence that do not agree how to group: the left
    /// one, the right one, and the ambiguous pair's own span — from the left
    /// operator through the right one.
    ///
    /// Three shapes reach this, and [`PhaseError::message`] says which:
    /// `left.name == right.name` is one `infix non` operator chained with
    /// itself (`a == b == c`); either side being `infix non` against a
    /// different operator is a non-associative operator that does not chain at
    /// all (`a < b > c`); and a `left` against a `right` is the genuine
    /// disagreement about which side groups first (`a << b >> c`).
    AmbiguousOperatorPrecedence(AmbiguousOperator, AmbiguousOperator, NodeSpan),
    BindingPatternsInvalidLen(NodeSpan),
    /// A declaration with a type annotation and no body, and where the annotation
    /// was written — which is the only part of it there is to point at.
    NoBindings(NodeSpan),
    /// A name used as a value that nothing in scope declares, where it was
    /// written — the identifier alone, not the declaration around it — and,
    /// when one name in scope is a close enough typo-distance match, a
    /// suggestion for what was meant (`ERR-7`).
    VariableNotFound(QualName, NodeSpan, Option<Name>),
    /// A name exposed unqualified by more than one imported module, and where it
    /// was used. Each candidate module is paired with where the name is declared
    /// there — `Some` when that module's `Interface` knows both its file and the
    /// declaration's span, `None` for a hand-built interface (a test) or one built
    /// before its module's file was known (`ERR-5`) — and with whether that import
    /// was written by the module under check or supplied by [the default import
    /// list](../../docs/spec/modules.md#the-default-imports), which a default
    /// entry participates in exactly as a written import does
    /// (`SPEC-32`/[`DEC-15`](../../docs/decisions/dec-15.md)); the note calls out
    /// a default contributor as implicit.
    AmbiguousVariables(
        Name,
        Vec<(ModuleName, Option<super::SourceSpan>, ImportOrigin)>,
        NodeSpan,
    ),
    /// A constructor used in an expression or a pattern that nothing in scope
    /// declares, where it was written, and an optional "did you mean …?"
    /// suggestion (`ERR-7`).
    VariantNotFound(QualName, NodeSpan, Option<Name>),
    /// Nothing constructs this today — `Environment::find_type_constructor` returns
    /// at most one constructor per name, so it has no way to report an ambiguity.
    /// It is the designated rejection path once it can, and carries the span the
    /// construction site would have, alongside each candidate's declaration
    /// location — see [`Error::AmbiguousVariables`].
    AmbiguousVariants(
        Name,
        Vec<(ModuleName, Option<super::SourceSpan>, ImportOrigin)>,
        NodeSpan,
    ),
    /// A tuple type, pattern or expression had a size other than 2 or 3 (the
    /// only sizes the language supports).
    ///
    /// Nothing constructs this today, and it is kept deliberately. Both ASTs
    /// now hold their tuples in [`Tuple`], which cannot represent another
    /// arity, and the grammar has one production per arity — so a bad tuple is
    /// a parse error and never reaches canonicalization. This variant is the
    /// designated rejection path should a future source of tuples (a REPL, a
    /// desugaring pass) build one from a list.
    InvalidTupleSize(usize),
    /// A function was declared with multiple bindings (multi-clause definitions),
    /// which the compiler does not support yet.
    MultipleBindingsUnsupported(Name, NodeSpan),
    /// A class head that is not an uppercase name applied to exactly one type variable,
    /// and where the head was written, context excluded.
    InvalidClassHead(NodeSpan),
    /// A class declared where a type or an earlier class of the module already has its
    /// name, the two sharing [one namespace](../../docs/spec/name-resolution.md#namespaces):
    /// the name, which kind of declaration had it first, the class's head line and the
    /// other declaration's.
    ClassNameTaken(Name, NameTakenBy, NodeSpan, NodeSpan),
    /// A class name — a superclass, an instance's class, a constraint in an instance's
    /// or an annotation's context — that nothing in scope declares: the name as
    /// written, and the constraint or the instance head it was written in.
    ClassNotFound(Name, NodeSpan),
    /// A constraint in a class head, an instance's context or an annotation's context
    /// whose argument is not one type variable, and the constraint's span.
    ConstraintNotOnVariable(NodeSpan),
    /// A constraint in a class head or an instance's context on a type variable the head
    /// does not bind: the variable, and where it was written.
    ConstraintVariableUnbound(Name, NodeSpan),
    /// A constraint in an annotation's context on a type variable the annotation's type
    /// does not mention, so no caller could say which type it meant: the variable, and
    /// where it was written.
    ConstraintVariableNotInType(Name, NodeSpan),
    /// A member signature written with a context of its own: the member, and the
    /// context's span. A member signature carries no constraint.
    MemberConstrained(Name, NodeSpan),
    /// A member signature marked `unsafe`, which only a facade signature may be: the
    /// member, and the signature's span, which starts at the word.
    MemberUnsafe(Name, NodeSpan),
    /// A member signature that never mentions the class variable, so no use of it could
    /// say which instance it meant: the member, the class, the class variable, and the
    /// signature's span.
    MemberMissesClassVariable(Name, Name, Name, NodeSpan),
    /// Two member signatures of one name in one class: the name, the second signature's
    /// span and the first's.
    MemberDeclaredTwice(Name, NodeSpan, NodeSpan),
    /// A member whose name another value of the module already has — a top-level
    /// declaration, or a member of another of its classes. A member is a top-level
    /// value of the module declaring its class. Carries the member, its class, the
    /// other class when the other is a member, the member's signature span and the
    /// other declaration's.
    MemberNameTaken(Name, Name, Option<Name>, NodeSpan, NodeSpan),
    /// A member named on its own in its module's `exposing` list, where it is exposed
    /// with its class or not at all: the member, its class, and the entry's span.
    MemberExposedAlone(Name, Name, NodeSpan),
    /// `Name(..)` in a module's `exposing` list naming one of its classes, which has no
    /// constructors: the class, and the entry's span.
    ClassExposedWithConstructors(Name, NodeSpan),
    /// An instance head that is not one of the forms
    /// [a head may take](../../docs/spec/type-classes.md#what-an-instance-is-declared-for):
    /// what is wrong with it, and the span of the part that is.
    InvalidInstanceHead(InstanceHeadProblem, NodeSpan),
    /// An instance binding that names no member of the class: the binding's name, the
    /// class, and the binding's span.
    InstanceBindingNotMember(Name, Name, NodeSpan),
    /// A member of the class no binding of the instance defines: the member, the class,
    /// and the instance's head line.
    InstanceMemberMissing(Name, Name, NodeSpan),
    /// A member an instance binds twice: the member, the second binding's span and the
    /// first's.
    InstanceMemberBoundTwice(Name, NodeSpan, NodeSpan),
    /// An instance declared in a module that declares neither its class nor its head's
    /// type ([the orphan rule](../../docs/spec/type-classes.md#where-an-instance-may-be-declared)):
    /// the instance's class and head, and its head line. The class and a declared head
    /// type each carry the module that declares them, which the message names.
    OrphanInstance(Box<InstanceName>, NodeSpan),
    /// A second instance of one class for one head name: that class and head, the
    /// second instance's head line, and where the first was declared.
    DuplicateInstance(Box<InstanceName>, NodeSpan, DeclarationSite),
    /// An instance of a class with a superclass, with no instance of the superclass for
    /// the same head name in scope: the instance's class and head, the superclass, and
    /// the instance's head line.
    MissingSuperclassInstance(Box<InstanceName>, QualName, NodeSpan),
    /// A `derived` in a class body for a name the class does not declare as a member: the
    /// name as written, the class, and where `derived name` was written.
    DerivationForNonMember(Name, Name, NodeSpan),
    /// A second `derived` for a member that has one: the member, the second derivation's
    /// span and the first's. A member has at most one.
    DerivationRepeated(Name, NodeSpan, NodeSpan),
    /// A derivation for a member whose signature cannot carry one: the member, what is
    /// wrong with the signature, where `derived member` was written and where the
    /// member's signature was.
    DerivationSignature(Name, DerivationSignatureProblem, NodeSpan, NodeSpan),
    /// A derivation without a binding its member's signature calls for: the binding, the
    /// member, and where `derived member` was written.
    DerivationBindingMissing(Name, Name, NodeSpan),
    /// A binding in a derivation that its member's signature does not call for: the
    /// binding, the member, the bindings the derivation takes, and the binding's span.
    DerivationBindingUnexpected(Name, Name, Vec<Name>, NodeSpan),
    /// A binding written twice in one derivation: the binding, the member, the second
    /// one's span and the first's.
    DerivationBindingRepeated(Name, Name, NodeSpan, NodeSpan),
    /// A binding in a derivation written with more parameters than the walk supplies it:
    /// the binding, the member, how many parameters it may take, and the binding's span.
    /// The compiler's limit rather than the language's: canonical code has no lambda to place
    /// such a binding with, and `LANG-87` is the ticket.
    DerivationBindingTakesTooMany(Name, Name, usize, NodeSpan),
    /// A class that derives some of its members and not the rest: the class, the members
    /// left out, and the class's head line.
    DerivationIncomplete(Name, Vec<Name>, NodeSpan),
    /// An instance asking to be derived for a class that is not derivable — one whose
    /// members do not all carry a derivation: the class, and the word `derived`.
    DerivedInstanceNotDerivable(Name, NodeSpan),
    /// A `derived` instance for a type with no shape for a walk to read: what is wrong, and
    /// the word `derived`.
    DerivedInstanceNoShape(DerivedShapeProblem, NodeSpan),
    /// A `derived` instance for a type holding an argument with no instance of the
    /// class: which argument, and the word `derived`.
    DerivedInstanceRequires(Box<DerivedRequirement>, NodeSpan),
    /// A context written on a `derived` instance that does not provide a constraint the
    /// type's arguments need: which constraint, the written context's span and the word
    /// `derived`.
    DerivedInstanceContextTooNarrow(Box<DerivedContextGap>, NodeSpan, NodeSpan),
    /// A type name applied to the wrong number of arguments: the name, its
    /// declaration's own arity, the number of arguments actually written, and
    /// `tpe.span` — the whole application, so the caret covers every argument
    /// along with the name (`BUG-17`).
    TypeArityMismatch(Name, usize, usize, NodeSpan),
    /// A type name written in a type expression that nothing in scope declares:
    /// the name exactly as it was written, and `tpe.span` — the application, so
    /// the caret covers the name along with whatever it was applied to.
    ///
    /// The declarations of the module under check are in scope here as much as
    /// its imports are, so this is a name neither half offers. Only the
    /// `TypeKind::Unqualified` arm of `Type::from_parser_type` raises it: a
    /// type *variable* arrives as `TypeKind::Variable` and is bound by the
    /// annotation it appears in, so it resolves through nothing and cannot
    /// reach here.
    TypeNotFound(Name, NodeSpan),
    /// Something other than a constructor name and its arguments written in a
    /// `type` declaration's variant position: what was written there, and that
    /// variant's own span rather than the declaration's, so the caret sits under
    /// the offending variant alone (`BUG-18`).
    InvalidVariant(InvalidVariantKind, NodeSpan),
    /// An opaque scalar's `type` declaration — `Basics.Int`, `Basics.Float`,
    /// `Char.Char` or `String.String` — whose body is something other than
    /// exactly its own name with no arguments (`LANG-59`,
    /// [`DEC-15` decision
    /// 2](../../docs/decisions/dec-15.md#2--a-scalar-type-is-declared-in-zelkova-and-an-opaque-ones-declaration-names-itself)).
    /// Nothing in the language constructs or inspects a value of one of these
    /// four, so the declaration exists to be read rather than built from, and a
    /// body naming anything else — a different type, extra variants, arguments —
    /// would describe a representation the language does not have.
    ///
    /// Carries the declaration's qualified name and the whole declaration's span
    /// (`tpe.span`), the same position [`Error::InvalidVariant`] would rather than
    /// a per-variant one — the check runs on the shape of the whole variant list,
    /// not on one variant that is wrong among otherwise-good ones.
    InvalidScalarDeclaration(QualName, NodeSpan),
    /// Something other than a constraint written in front of an annotation's
    /// `=>`: what was written, and that piece's own span — one constraint of a
    /// parenthesised list rather than the whole context, so the caret sits under
    /// the part that is wrong.
    ///
    /// The grammar parses each element of a context as a type (see
    /// `parser::Context`), so every shape a type can take arrives here;
    /// `validate_context` is what narrows each one to a constraint.
    InvalidConstraint(InvalidConstraintKind, NodeSpan),
    /// A label given to two fields of one record type, record, update or record
    /// pattern: the label, which of the four forms it was found in, where the repeat
    /// was written and where the first field with that label was. Both spans are the
    /// label's alone, so the primary caret sits under the repeat and a secondary one
    /// under the first.
    ///
    /// [Records](../../docs/spec/records.md) makes it an error in all four, once
    /// where it states it for [a record type](../../docs/spec/records.md#the-type),
    /// [a record](../../docs/spec/records.md#building-a-record),
    /// [an update](../../docs/spec/records.md#updating-a-record) and
    /// [a record pattern](../../docs/spec/records.md#record-patterns): a record type is
    /// a set of fields, a record and an update say each field's value once, and a
    /// record pattern says once what each field it names is matched against. One error
    /// per repeat, each naming the first, so a label written three times is two.
    RepeatedLabel(Name, RecordForm, NodeSpan, NodeSpan),

    // Binding module
    InfixDeclared(Name, NodeSpan),
    TypeDeclared(Name, NodeSpan),
    /// A `class` declaration in a `module foreign` facade, which holds signatures only:
    /// the class's head line.
    ClassDeclared(NodeSpan),
    /// An `instance` declaration in a `module foreign` facade: its head line.
    InstanceDeclared(NodeSpan),
    NoTypeInBinding(Name, NodeSpan),
    /// An annotation outside a `module foreign` facade was marked `unsafe`: the
    /// name it annotates, and the annotation's span — which the grammar takes
    /// from the modifier, so the caret starts on the word itself.
    ///
    /// `unsafe` asserts something about the companion behind a facade signature
    /// (`LANG-53`, [`DEC-12`](../../docs/decisions/dec-12.md)). There is no
    /// companion behind an ordinary declaration for it to be a claim about, and
    /// accepting the word there would make it mean nothing in half the places it
    /// can be written.
    UnsafeOutsideFacade(Name, NodeSpan),
    /// A `module foreign` facade signature naming a type variable or a
    /// function type, in a parameter or in the result, once the arrows
    /// separating a facade's own parameters are stripped
    /// (`docs/spec/interop.md#what-a-facade-signature-may-not-name`): the
    /// value's name, which form was found, and `function.annotation_span`.
    ///
    /// The span is the whole annotation rather than the offending piece of it,
    /// because a canonical `Type` carries no span of its own — see
    /// `Type::from_parser_type`'s doc comment — and the annotation is the
    /// finest caret available without first teaching that conversion to keep
    /// per-node spans.
    FacadeTypeNotAdmitted(Name, FacadeRejectedKind, NodeSpan),
    /// An unmarked `module foreign` facade signature whose result type — the
    /// last piece `facade_signature_pieces` returns, once
    /// `check_facade_admitted_type` has already accepted it — is not exactly
    /// `Task (Result Failure a)`: the value's name, and `function.annotation_span`.
    ///
    /// [An effectful facade](../../docs/spec/interop.md#an-effectful-facade)
    /// settles the shape: a facade declares an effect unless its signature is
    /// marked [`unsafe`](../../docs/spec/interop.md#an-unsafe-facade), and an
    /// effectful facade's result type must be exactly `Task (Result Failure a)`.
    /// Never raised for a signature `function.marked_unsafe` — `unsafe` removes
    /// the requirement, not the boundary check itself.
    ///
    /// The span is the whole annotation rather than the offending piece of it,
    /// for the same reason [`Error::FacadeTypeNotAdmitted`] uses it — a
    /// canonical `Type` carries no span of its own.
    FacadeResultNotEffect(Name, NodeSpan),
    /// `Task` named anywhere in a `module foreign` facade signature other than
    /// the whole of an unmarked facade's result: the value's name, and
    /// `function.annotation_span`.
    ///
    /// [An effectful facade](../../docs/spec/interop.md#an-effectful-facade)
    /// confines `Task` to that one position — never as an argument, and never
    /// nested inside another type, whether or not the signature is marked
    /// [`unsafe`](../../docs/spec/interop.md#an-unsafe-facade). `Task` is
    /// recognised by the qualified name of its declaration
    /// (`is_task_declaration`) and never by spelling, so a module's own type
    /// named `Task` is an ordinary union here, not this.
    ///
    /// The span is the whole annotation, as [`Error::FacadeTypeNotAdmitted`]'s
    /// is.
    FacadeTaskMisplaced(Name, NodeSpan),
    /// A `module foreign` facade signature written with a constraint context:
    /// the value's name, and the context's span.
    ///
    /// A facade is monomorphic — its signature names the types the code behind
    /// it really handles ([Type
    /// classes](../../docs/spec/type-classes.md#a-constrained-function-may-not-be-a-foreign-facade),
    /// [`DEC-2` decision 6](../../docs/decisions/dec-2.md)) — and a constrained
    /// function is specialised per instance out of a body a facade does not have.
    /// Reported whatever the context's shape, a well-formed one included.
    FacadeConstrained(Name, NodeSpan),

    /// A parameterless binding that depends on itself — [evaluation
    /// semantics](../../docs/spec/evaluation-semantics.md#a-binding-may-not-depend-on-itself):
    /// such a binding is evaluated once, before the program runs, after everything it
    /// depends on, and a cycle through it describes no such order. *Depends on* is
    /// transitive mention: the declarations its body mentions, the ones *their* bodies
    /// mention, and so on, through functions as well as parameterless bindings — see
    /// `dependency_graph`.
    ///
    /// One entry per member of the cycle — every declaration of one strongly-connected
    /// component of that graph — each carrying its own declaration's span
    /// (`Value::span()`) and whether it is a function. Length 1 for a parameterless
    /// binding that mentions itself (`x = x`), length 2 or more for a cycle running
    /// through several declarations (`a = b` beside `b = a`, or `a = f 1` beside `f x =
    /// a`). `check_self_dependency` orders the members parameterless bindings first,
    /// then functions, each group by name, so the first entry is always a parameterless
    /// binding and the order is not an artifact of traversal. `labels()` gives that first
    /// entry the primary label and every other entry a secondary one.
    ///
    /// A cycle of functions only is never reported: a function's value exists before its
    /// body runs, so `f n = f n` and mutual recursion between two functions are untouched
    /// by this check.
    SelfDependency(Vec<CycleMember>),

    // Utility error
    Many(Vec<Error>),
}

/// One declaration of a cycle [`Error::SelfDependency`] reports.
#[derive(Debug, Clone)]
pub struct CycleMember {
    pub name: Name,
    /// The whole declaration, as `Value::span()` gives it.
    pub span: NodeSpan,
    /// Whether the declaration names a parameter. A cycle is only ever reported when it
    /// holds at least one member for which this is `false`.
    pub function: bool,
}

/// What was written where a `type` declaration expected a variant — see
/// [`Error::InvalidVariant`].
///
/// A variant is a constructor name followed by zero or more type arguments, and
/// nothing else. The grammar does not enforce that: it parses a variant list with
/// the general `Type` production, so every shape a type expression can take reaches
/// `do_types`. This enum names the five that are not a variant, one per remaining
/// [`parser::TypeKind`], so each can say what it is in the words of the source.
#[derive(Debug, PartialEq, Clone)]
pub enum InvalidVariantKind {
    /// A name beginning with a lowercase letter, which the grammar reads as a type
    /// variable — `type Colour = red`, and a mistyped constructor name along with
    /// it. Carries the name so the message can quote it.
    LowercaseName(Name),
    /// A tuple type — `type Pair = (Int, Int)`.
    Tuple,
    /// The unit type — `type Nothing = ()`.
    Unit,
    /// A function type — `type Wrapper = Wrap Int -> Int`. The arrow is the *whole*
    /// variant rather than a suffix of it, `Wrap Int` being its left operand, so
    /// there is no constructor here to keep either.
    Arrow,
    /// A record type — `type Point = { x : Int }`. A record type is declared by no
    /// `type` declaration; one may sit inside a variant, `Point { x : Int }`.
    Record,
}

/// What was written in front of `=>` in place of a constraint — see
/// [`Error::InvalidConstraint`].
///
/// A constraint is an uppercase name applied to one or more type arguments, and a
/// context is one constraint or a parenthesised, comma-separated list of them
/// ([`parser::Context`]). This names every other shape an element of that list can
/// take, one per remaining [`parser::TypeKind`] case.
#[derive(Debug, PartialEq, Clone)]
pub enum InvalidConstraintKind {
    /// A type variable on its own — `a => a`.
    Variable(Name),
    /// An uppercase name with no argument — `Int => a`, and so each half of
    /// `(Int, Char) => a`. Carries the name so the message can quote it.
    Unapplied(Name),
    /// A function type — `Int -> Int => a`.
    Arrow,
    /// A tuple inside the parenthesised list — `((Eq a, Eq b), Eq c) => a`. The
    /// parser reads the outermost parentheses as the list, so only a tuple nested
    /// in it reaches here.
    Tuple,
    /// The unit type — `() => a`.
    Unit,
    /// A record type — `{ x : a } => a`.
    Record,
}

/// What had a class's name first — see [`Error::ClassNameTaken`].
#[derive(Debug, PartialEq, Clone, Copy)]
pub enum NameTakenBy {
    /// A `type` declaration of the same module.
    Type,
    /// An earlier `class` declaration of the same module.
    Class,
}

/// What is wrong with an instance head — see [`Error::InvalidInstanceHead`].
///
/// A head is a class name applied to one type, and that type is a declared type applied
/// to distinct variables, a tuple of distinct variables, or `()`.
#[derive(Debug, PartialEq, Clone)]
pub enum InstanceHeadProblem {
    /// Something other than a class name applied to a type — `instance a where`.
    NotAClass,
    /// The class applied to some number of types other than one — `instance Eq Int Char`.
    ClassApplied(usize),
    /// A bare type variable — `instance Eq a`.
    Variable(Name),
    /// A function type — `instance Eq (a -> b)`.
    Function,
    /// A record type.
    Record,
    /// An argument of the head's type that is not a type variable — `Int` in
    /// `instance Eq (Maybe Int)`.
    ArgumentNotVariable,
    /// A variable the head already bound — the second `a` of `instance Eq (Pair a a)`.
    RepeatedVariable(Name),
}

/// The two forms [What a facade signature may not
/// name](../../docs/spec/interop.md#what-a-facade-signature-may-not-name)
/// rejects — see [`Error::FacadeTypeNotAdmitted`].
#[derive(Debug, PartialEq, Clone, Copy)]
pub enum FacadeRejectedKind {
    /// A type variable, which excludes no value: there is nothing for a
    /// runtime predicate to decide.
    Variable,
    /// A function type, wherever it is found — as the signature's own result
    /// or nested inside a parameter, a tuple or a union's argument.
    Function,
}

/// Canonicalization errors name source constructs — a value, a type, an operator —
/// so their messages can be written in the same words the user wrote.
///
/// The variants whose construction site had a declaration in hand also point at it;
/// see the enum's own documentation for why the others do not.
impl PhaseError for Error {
    fn message(&self) -> String {
        match self {
            Error::ExportNotFound(name, tpe, _) => format!(
                "`{}` is exposed by this module but no {} of that name is declared in it",
                name,
                export_type_noun(tpe)
            ),
            Error::ExportedValueNotAnnotated(name, _, _) => format!(
                "`{}` is exposed by this module but has no type annotation",
                name
            ),
            Error::EnvironmentErrors(errors) => match errors.as_slice() {
                [only] => only.message(),
                many => format!("{} of this module's imports could not be resolved", many.len()),
            },
            Error::InfixReferenceInvalidValue(infix, function, _) => format!(
                "the infix operator `{}` is declared as `{}`, which is not a value declared in this module",
                infix, function
            ),
            Error::AmbiguousOperatorPrecedence(left, right, _) => {
                // Three shapes, and the everyday one is the middle: `Basics`
                // declares six operators `infix non 4`, so `a < b > c` reaches
                // here with two *different* operators that do not disagree about
                // anything — both say they do not chain. Calling that a
                // disagreement about which side groups first would name a reason
                // that is not the reason.
                if left.name == right.name {
                    format!(
                        "`{}` is declared `infix non`, so it cannot be chained with itself without parentheses to say which application comes first",
                        left.name
                    )
                } else if left.is_non_associative() && right.is_non_associative() {
                    format!(
                        "`{}` and `{}` are both declared `infix non` at the same precedence, so neither groups the other and this needs parentheses",
                        left.name, right.name
                    )
                } else if left.is_non_associative() || right.is_non_associative() {
                    let (non, other) = if left.is_non_associative() {
                        (&left.name, &right.name)
                    } else {
                        (&right.name, &left.name)
                    };

                    format!(
                        "`{}` is declared `infix non`, so it does not chain with `{}` at the same precedence without parentheses",
                        non, other
                    )
                } else {
                    format!(
                        "`{}` and `{}` have the same precedence but disagree on which side groups first, so this needs parentheses to say which one applies first",
                        left.name, right.name
                    )
                }
            }
            Error::BindingPatternsInvalidLen(_) => {
                "the arguments of this declaration do not line up with its type annotation"
                    .to_owned()
            }
            Error::NoBindings(_) => {
                "this declaration has a type annotation but no body".to_owned()
            }
            Error::VariableNotFound(name, _, _) => {
                format!("cannot find a value named `{}`", name.to_name())
            }
            Error::AmbiguousVariables(name, _, _) => {
                format!("`{}` is exposed by several imported modules", name)
            }
            Error::VariantNotFound(name, _, _) => {
                format!("cannot find a type constructor named `{}`", name.to_name())
            }
            Error::AmbiguousVariants(name, _, _) => format!(
                "the type constructor `{}` is exposed by several imported modules",
                name
            ),
            Error::InvalidTupleSize(size) => format!(
                "a tuple has two or three elements, this one has {}",
                size
            ),
            Error::MultipleBindingsUnsupported(name, _) => format!(
                "`{}` is declared over several bindings, which is not supported yet",
                name
            ),
            Error::InvalidClassHead(_) => {
                "a class head is the class's name applied to one type variable".to_owned()
            }
            Error::ClassNameTaken(name, NameTakenBy::Type, _, _) => format!(
                "`{}` is declared as both a type and a class, and the two share one namespace",
                name
            ),
            Error::ClassNameTaken(name, NameTakenBy::Class, _, _) => {
                format!("the class `{}` is declared twice", name)
            }
            Error::ClassNotFound(name, _) => format!("cannot find a class named `{}`", name),
            Error::ConstraintNotOnVariable(_) => {
                "a constraint is a class applied to one type variable".to_owned()
            }
            Error::ConstraintVariableUnbound(name, _) => format!(
                "the type variable `{}` is constrained, but the head does not bind it",
                name
            ),
            Error::ConstraintVariableNotInType(name, _) => format!(
                "the type variable `{}` is constrained, but the annotated type does not mention it",
                name
            ),
            Error::MemberConstrained(name, _) => format!(
                "the member `{}` is written with a constraint, and a member signature carries none",
                name
            ),
            Error::MemberUnsafe(name, _) => format!(
                "the member `{}` is marked `unsafe`, which only a signature in a `module foreign` facade may be",
                name
            ),
            Error::MemberMissesClassVariable(name, class, variable, _) => format!(
                "the member `{}` of `{}` never mentions the class variable `{}`, so no use of it could say which instance it means",
                name, class, variable
            ),
            Error::MemberDeclaredTwice(name, _, _) => {
                format!("the member `{}` is declared twice in this class", name)
            }
            Error::MemberNameTaken(name, class, Some(other), _, _) => format!(
                "`{}` is a member of both `{}` and `{}`",
                name, other, class
            ),
            Error::MemberNameTaken(name, class, None, _, _) => format!(
                "`{}` is a member of `{}` and is also declared as a value of this module",
                name, class
            ),
            Error::MemberExposedAlone(name, class, _) => format!(
                "`{}` is a member of `{}`, and a member is exposed with its class, not on its own",
                name, class
            ),
            Error::ClassExposedWithConstructors(name, _) => format!(
                "`{}` is a class, and a class has no constructors for `(..)` to expose",
                name
            ),
            Error::InvalidInstanceHead(problem, _) => match problem {
                InstanceHeadProblem::NotAClass => {
                    "an instance head is a class name applied to the type the instance is for"
                        .to_owned()
                }
                InstanceHeadProblem::ClassApplied(n) => format!(
                    "an instance head applies its class to one type, and this one applies it to {}",
                    n
                ),
                InstanceHeadProblem::Variable(name) => format!(
                    "an instance is for a type, and the type variable `{}` is not one",
                    name
                ),
                InstanceHeadProblem::Function => {
                    "an instance cannot be declared for a function type".to_owned()
                }
                InstanceHeadProblem::Record => {
                    "an instance cannot be declared for a record type".to_owned()
                }
                InstanceHeadProblem::ArgumentNotVariable => {
                    "every argument of an instance head's type must be a type variable"
                        .to_owned()
                }
                InstanceHeadProblem::RepeatedVariable(name) => format!(
                    "the type variable `{}` is written twice in this instance head",
                    name
                ),
            },
            Error::InstanceBindingNotMember(name, class, _) => {
                format!("`{}` is not a member of the class `{}`", name, class)
            }
            Error::InstanceMemberMissing(name, class, _) => format!(
                "this instance does not define `{}`, a member of the class `{}`",
                name, class
            ),
            Error::InstanceMemberBoundTwice(name, _, _) => {
                format!("this instance defines `{}` twice", name)
            }
            Error::OrphanInstance(instance, _) => match instance.head.module() {
                Some(head_module) => format!(
                    "`{}` is declared in `{}` and {} in `{}`; an instance may go in either",
                    instance.class.unqualified_name(),
                    instance.class.module_name(),
                    instance.head.describe(),
                    head_module.name()
                ),
                None => format!(
                    "`{}` is declared in `{}`, and an instance of it for {} may go only there",
                    instance.class.unqualified_name(),
                    instance.class.module_name(),
                    instance.head.describe()
                ),
            },
            Error::DuplicateInstance(instance, _, _) => format!(
                "`{}` already has an instance for {}",
                instance.class.unqualified_name(),
                instance.head.describe()
            ),
            Error::MissingSuperclassInstance(instance, superclass, _) => format!(
                "an instance of `{}` for {} needs an instance of its superclass `{}` for {}",
                instance.class.unqualified_name(),
                instance.head.describe(),
                superclass.unqualified_name(),
                instance.head.describe()
            ),
            Error::DerivationForNonMember(member, class, _) => format!(
                "`derived {}` is in the class `{}`, which has no member `{}`",
                member, class, member
            ),
            Error::DerivationRepeated(member, _, _) => {
                format!("the member `{}` has a derivation already", member)
            }
            Error::DerivationSignature(member, problem, _, _) => match problem {
                DerivationSignatureProblem::NoClassValue => format!(
                    "the member `{}` takes no value of the class's type, so there is none for a derivation to walk",
                    member
                ),
                DerivationSignatureProblem::ResultMentionsClassVariable => format!(
                    "the member `{}` answers with a type that mentions the class variable, which a derivation cannot build",
                    member
                ),
                DerivationSignatureProblem::Shape => format!(
                    "the signature of `{}` is neither a value of the class's type nor two, followed by an answer",
                    member
                ),
            },
            Error::DerivationBindingMissing(binding, member, _) => format!(
                "the derivation of `{}` has no `{}`",
                member, binding
            ),
            Error::DerivationBindingUnexpected(binding, member, takes, _) => format!(
                "`{}` is not a binding of the derivation of `{}`, which takes {}",
                binding,
                member,
                name_list(takes)
            ),
            Error::DerivationBindingRepeated(binding, member, _, _) => format!(
                "the derivation of `{}` defines `{}` twice",
                member, binding
            ),
            Error::DerivationBindingTakesTooMany(binding, member, most, _) => format!(
                "`{}` in the derivation of `{}` takes at most {}, the ones the walk gives it",
                binding,
                member,
                parameter_count(*most)
            ),
            Error::DerivationIncomplete(class, left_out, _) => format!(
                "the class `{}` derives some of its members and not {}, and an instance of it could only be half derived",
                class,
                name_list(left_out)
            ),
            Error::DerivedInstanceNotDerivable(class, _) => format!(
                "`{}` cannot be derived: not every member of it carries a derivation",
                class
            ),
            Error::DerivedInstanceNoShape(problem, _) => match problem {
                DerivedShapeProblem::Scalar(tpe) => format!(
                    "`{}` is a scalar type, which has no shape for a derivation to walk",
                    tpe
                ),
                DerivedShapeProblem::NoConstructors(tpe) => format!(
                    "the constructors of `{}` are not in scope, and a derivation is read off them",
                    tpe
                ),
                DerivedShapeProblem::UnitHasNoElement(class) => format!(
                    "`()` has no element for the derivation of `{}` to begin at",
                    class
                ),
            },
            Error::DerivedInstanceContextTooNarrow(gap, _, _) => {
                let part = match &gap.part {
                    DerivedPart::Variant(variant) => format!("`{}`", variant),
                    DerivedPart::Element(position) => format!("element {} of the tuple", position),
                };
                format!(
                    "{} holds a `{}`, which needs `{}` for the derived instance of `{}`, and the instance's context does not provide it",
                    part, gap.argument, gap.missing, gap.class
                )
            }
            Error::DerivedInstanceRequires(requirement, _) => {
                let part = match &requirement.part {
                    DerivedPart::Variant(variant) => format!("`{}`", variant),
                    DerivedPart::Element(position) => format!("element {} of the tuple", position),
                };
                if requirement.argument == requirement.missing {
                    if requirement.function {
                        format!(
                            "{} holds a function, `{}`, and no instance of `{}` can be declared for one",
                            part, requirement.missing, requirement.class
                        )
                    } else {
                        format!(
                            "{} holds a `{}`, which has no instance of `{}`",
                            part, requirement.missing, requirement.class
                        )
                    }
                } else {
                    format!(
                        "{} holds a `{}`, which needs an instance of `{}` for `{}`, and there is none",
                        part, requirement.argument, requirement.class, requirement.missing
                    )
                }
            }
            Error::TypeArityMismatch(name, declared, written, _) => format!(
                "`{}` takes {}, but is applied to {} here",
                name,
                type_argument_count(*declared),
                type_argument_count(*written)
            ),
            Error::TypeNotFound(name, _) => {
                format!("cannot find a type named `{}`", name)
            }
            Error::InvalidVariant(kind, _) => match kind {
                InvalidVariantKind::LowercaseName(name) => format!(
                    "`{}` is not a constructor name: a constructor name begins with an uppercase letter",
                    name
                ),
                InvalidVariantKind::Tuple => {
                    "a variant is a constructor name followed by its arguments, and this one is a tuple type"
                        .to_owned()
                }
                InvalidVariantKind::Unit => {
                    "a variant is a constructor name followed by its arguments, and this one is the unit type"
                        .to_owned()
                }
                InvalidVariantKind::Arrow => {
                    "a variant is a constructor name followed by its arguments, and this one is a function type"
                        .to_owned()
                }
                InvalidVariantKind::Record => {
                    "a variant is a constructor name followed by its arguments, and this one is a record type"
                        .to_owned()
                }
            },
            Error::InvalidScalarDeclaration(name, _) => format!(
                "`{}` is an opaque scalar type, so its declaration must be exactly `type {} = {}`",
                name.to_name(),
                name.unqualified_name(),
                name.unqualified_name()
            ),
            Error::RepeatedLabel(label, form, _, _) => format!(
                "`{}` labels two fields of one {}, and a label may be given only once",
                label,
                match form {
                    RecordForm::Type => "record type",
                    RecordForm::Record => "record",
                    RecordForm::Update => "update",
                    RecordForm::Pattern => "record pattern",
                }
            ),
            Error::InvalidConstraint(kind, _) => match kind {
                InvalidConstraintKind::Variable(name) => format!(
                    "only constraints may be written before `=>`, and the type variable `{}` is not one",
                    name
                ),
                InvalidConstraintKind::Unapplied(name) => format!(
                    "only constraints may be written before `=>`, and `{}` on its own is not one",
                    name
                ),
                InvalidConstraintKind::Arrow => {
                    "only constraints may be written before `=>`, and a function type is not one"
                        .to_owned()
                }
                InvalidConstraintKind::Tuple => {
                    "only constraints may be written before `=>`, and a tuple inside the list of constraints is not one"
                        .to_owned()
                }
                InvalidConstraintKind::Record => {
                    "only constraints may be written before `=>`, and a record type is not one"
                        .to_owned()
                }
                InvalidConstraintKind::Unit => {
                    "only constraints may be written before `=>`, and the unit type is not one"
                        .to_owned()
                }
            },
            Error::InfixDeclared(name, _) => format!(
                "a `module foreign` facade cannot declare an infix operator, but declares `{}`",
                name
            ),
            Error::TypeDeclared(name, _) => format!(
                "a `module foreign` facade cannot declare a type, but declares `{}`",
                name
            ),
            Error::ClassDeclared(_) => {
                "a `module foreign` facade cannot declare a class".to_owned()
            }
            Error::InstanceDeclared(_) => {
                "a `module foreign` facade cannot declare an instance".to_owned()
            }
            Error::NoTypeInBinding(name, _) => format!(
                "`{}` has no type annotation, and a `module foreign` facade is annotations only",
                name
            ),
            Error::UnsafeOutsideFacade(name, _) => format!(
                "`{}` is marked `unsafe`, which only a signature in a `module foreign` facade may be",
                name
            ),
            Error::FacadeTypeNotAdmitted(name, kind, _) => format!(
                "`{}` is a `module foreign` facade signature naming {}, which no target can check at the boundary",
                name,
                match kind {
                    FacadeRejectedKind::Variable => "a type variable",
                    FacadeRejectedKind::Function => "a function type",
                }
            ),
            Error::FacadeResultNotEffect(name, _) => format!(
                "`{}` is a `module foreign` facade signature with no `unsafe`, so it must return `Task (Result Failure a)`",
                name
            ),
            Error::FacadeTaskMisplaced(name, _) => format!(
                "`{}` names `Task` somewhere other than the whole of an unmarked facade's result",
                name
            ),
            Error::FacadeConstrained(name, _) => format!(
                "`{}` is a `module foreign` facade signature, and a facade signature may not carry a constraint",
                name
            ),
            // A one-binding cycle reads better as its own sentence than as "a
            // cycle of length one" — see the enum's own doc comment.
            // A larger cycle may hold functions, so it is described by its first member —
            // always a parameterless binding — and every member is named for what it is.
            Error::SelfDependency(members) => match members.as_slice() {
                [only] => format!(
                    "`{}` is a parameterless binding whose value depends on itself",
                    only.name
                ),
                [first, ..] => {
                    let mut named: Vec<String> = members
                        .iter()
                        .map(|member| {
                            if member.function {
                                format!("the function `{}`", member.name)
                            } else {
                                format!("`{}`", member.name)
                            }
                        })
                        .collect();
                    let last = named.pop().unwrap_or_default();
                    format!(
                        "`{}` needs its own value before it has one: {} and {} depend on each other",
                        first.name,
                        named.join(", "),
                        last
                    )
                }
                [] => "a parameterless binding depends on itself".to_owned(),
            },
            Error::Many(errors) => match errors.as_slice() {
                [only] => only.message(),
                many => format!("{} errors while canonicalizing this module", many.len()),
            },
        }
    }

    fn labels(&self) -> Vec<SpanLabel> {
        // One helper per shape: a variant either has a span and one thing to say
        // about it, or it delegates to the errors it wraps.
        let primary = |span: &NodeSpan, message: &str| match span.span() {
            Some(span) => vec![SpanLabel {
                span,
                message: message.to_owned(),
                primary: true,
                file: None,
            }],
            None => Vec::new(),
        };

        // A secondary label in the module under check, when the span has a position.
        let secondary = |span: &NodeSpan, message: String| {
            span.span().map(|span| SpanLabel {
                span,
                message,
                primary: false,
                file: None,
            })
        };

        // A secondary label pointing at where one ambiguous candidate is declared,
        // in *its own* module's file rather than the one being checked — the
        // mechanism `ERR-5` adds. `None` when that candidate's `Interface` cannot
        // say (a hand-built interface, or one built before its file was known)
        // yields no label for that candidate rather than one at the wrong place.
        let ambiguous_candidates =
            |candidates: &[(ModuleName, Option<super::SourceSpan>, ImportOrigin)]| {
                candidates
                    .iter()
                    .filter_map(|(module, source, _origin)| {
                        source.map(|s| SpanLabel {
                            span: s.span,
                            message: format!("also exposed here, by `{}`", module.name()),
                            primary: false,
                            file: Some(s.file),
                        })
                    })
                    .collect::<Vec<_>>()
            };

        match self {
            Error::ExportNotFound(name, _, span) => primary(
                span,
                &format!("`{}` is not declared anywhere in this module", name),
            ),
            Error::ExportedValueNotAnnotated(name, exposed_span, declared_span) => {
                let mut labels = primary(
                    exposed_span,
                    &format!("`{}` is exposed here but has no type annotation", name),
                );
                if labels.is_empty() {
                    // Reached only for `exposing (..)`: it names nothing
                    // individually, so there is no exposing-list position to put
                    // the primary label under — the declaration becomes the
                    // primary (and only) label instead of a secondary one.
                    labels = primary(
                        declared_span,
                        &format!(
                            "`{}` is exposed by `exposing (..)` but has no type annotation",
                            name
                        ),
                    );
                } else if let Some(span) = declared_span.span() {
                    labels.push(SpanLabel {
                        span,
                        message: "declared here, with no type annotation".to_owned(),
                        primary: false,
                        file: None,
                    });
                }
                labels
            }
            Error::InfixReferenceInvalidValue(_, _, span) => primary(span, "declared here"),
            // The two "declared here" labels go through `InfixDeclaration`, which
            // is what knows whether the declaration is in the module under check
            // or in an imported one. An operator's `infix` declaration is very
            // often not local — `Basics` declares every one the standard library
            // uses — and `Infix::span` is then a byte range in *that* module's
            // file, so a label built with `file: None` would underline unrelated
            // text in the importing module (`ERR-5` is the mechanism that avoids
            // it).
            Error::AmbiguousOperatorPrecedence(left, right, span) => {
                let mut labels = primary(span, "ambiguous without parentheses");

                labels.extend(
                    left.declaration
                        .label(format!("`{}` declared here", left.name)),
                );

                // Both sides naming the same operator is the `infix non`
                // self-conflict — they point at the very same declaration, so a
                // second label there would only repeat the first one.
                if left.name != right.name {
                    labels.extend(
                        right
                            .declaration
                            .label(format!("`{}` declared here", right.name)),
                    );
                }

                labels
            }
            // The four that name an identifier: the caret sits under the name the
            // user wrote, which is the whole point of spanning expressions and
            // patterns rather than only declarations. `VariableNotFound` and
            // `VariantNotFound` append their suggestion, when they have one, to
            // this same label rather than a free-floating note, so the caret and
            // the suggestion agree about which name is meant (`ERR-7`).
            Error::VariableNotFound(_, span, suggestion) => primary(
                span,
                &format!(
                    "no value of this name is in scope{}",
                    suggestion_suffix(suggestion)
                ),
            ),
            Error::AmbiguousVariables(_, candidates, span) => {
                let mut labels = primary(span, "this name is ambiguous");
                labels.extend(ambiguous_candidates(candidates));
                labels
            }
            Error::VariantNotFound(_, span, suggestion) => primary(
                span,
                &format!(
                    "no type constructor of this name is in scope{}",
                    suggestion_suffix(suggestion)
                ),
            ),
            Error::AmbiguousVariants(_, candidates, span) => {
                let mut labels = primary(span, "this type constructor is ambiguous");
                labels.extend(ambiguous_candidates(candidates));
                labels
            }
            Error::BindingPatternsInvalidLen(span) => primary(span, "declared here"),
            Error::NoBindings(span) => primary(span, "this annotation has no body"),
            Error::MultipleBindingsUnsupported(_, span) => primary(span, "declared here"),
            Error::InvalidClassHead(span) => primary(span, "not a class name and one variable"),
            Error::ClassNameTaken(name, taken_by, span, other) => {
                let mut labels = primary(span, &format!("the class `{}` is declared here", name));
                if let Some(other) = other.span() {
                    labels.push(SpanLabel {
                        span: other,
                        message: match taken_by {
                            NameTakenBy::Type => format!("the type `{}` is declared here", name),
                            NameTakenBy::Class => format!("`{}` is first declared here", name),
                        },
                        primary: false,
                        file: None,
                    });
                }
                labels
            }
            Error::ClassNotFound(_, span) => primary(span, "no class of this name is in scope"),
            Error::ConstraintNotOnVariable(span) => {
                primary(span, "this constrains something other than one type variable")
            }
            Error::ConstraintVariableUnbound(_, span) => {
                primary(span, "not bound by the head")
            }
            Error::ConstraintVariableNotInType(_, span) => {
                primary(span, "not mentioned by the type after `=>`")
            }
            Error::MemberConstrained(_, span) => primary(span, "a constraint on a member signature"),
            Error::MemberUnsafe(_, span) => primary(span, "marked `unsafe` here"),
            Error::MemberMissesClassVariable(_, _, variable, span) => primary(
                span,
                &format!("this signature does not mention `{}`", variable),
            ),
            Error::MemberDeclaredTwice(name, span, first) => {
                let mut labels = primary(span, &format!("`{}` is declared a second time here", name));
                labels.extend(secondary(first, format!("`{}` is first declared here", name)));
                labels
            }
            Error::MemberNameTaken(name, _, _, span, other) => {
                let mut labels = primary(span, &format!("the member `{}` is declared here", name));
                labels.extend(secondary(other, format!("`{}` is also declared here", name)));
                labels
            }
            Error::MemberExposedAlone(_, class, span) => primary(
                span,
                &format!("expose `{}` to expose this member", class),
            ),
            Error::ClassExposedWithConstructors(_, span) => {
                primary(span, "a class has no constructors")
            }
            Error::InvalidInstanceHead(problem, span) => primary(
                span,
                match problem {
                    InstanceHeadProblem::NotAClass => "not a class applied to a type",
                    InstanceHeadProblem::ClassApplied(_) => "a class applied to other than one type",
                    InstanceHeadProblem::Variable(_) => "a type variable, where a type belongs",
                    InstanceHeadProblem::Function => "a function type",
                    InstanceHeadProblem::Record => "a record type",
                    InstanceHeadProblem::ArgumentNotVariable => "not a type variable",
                    InstanceHeadProblem::RepeatedVariable(_) => "already bound in this head",
                },
            ),
            Error::InstanceBindingNotMember(_, class, span) => {
                primary(span, &format!("not a member of `{}`", class))
            }
            Error::InstanceMemberMissing(name, _, span) => {
                primary(span, &format!("this instance has no definition of `{}`", name))
            }
            Error::InstanceMemberBoundTwice(name, span, first) => {
                let mut labels = primary(span, &format!("`{}` is defined a second time here", name));
                labels.extend(secondary(first, format!("`{}` is first defined here", name)));
                labels
            }
            Error::OrphanInstance(instance, span) => primary(
                span,
                &match instance.head.module() {
                    Some(head_module) => format!(
                        "declare this instance in `{}` or in `{}`",
                        instance.class.module_name(),
                        head_module.name()
                    ),
                    None => format!(
                        "declare this instance in `{}`",
                        instance.class.module_name()
                    ),
                },
            ),
            Error::DuplicateInstance(_, span, first) => {
                let mut labels = primary(span, "declared a second time here");
                labels.extend(first.label("first declared here".to_owned()));
                labels
            }
            Error::MissingSuperclassInstance(instance, superclass, span) => primary(
                span,
                &format!(
                    "no instance of `{}` for {} is in scope",
                    superclass.unqualified_name(),
                    instance.head.describe()
                ),
            ),
            Error::DerivationForNonMember(member, class, span) => {
                primary(span, &format!("`{}` is not a member of `{}`", member, class))
            }
            Error::DerivationRepeated(member, span, first) => {
                let mut labels = primary(span, &format!("`{}` is derived a second time here", member));
                labels.extend(secondary(first, format!("`{}` is first derived here", member)));
                labels
            }
            Error::DerivationSignature(_, problem, span, signature) => {
                let mut labels = primary(
                    span,
                    match problem {
                        DerivationSignatureProblem::NoClassValue => "no value to walk",
                        DerivationSignatureProblem::ResultMentionsClassVariable => {
                            "a derivation cannot build a value of the class's type"
                        }
                        DerivationSignatureProblem::Shape => "not a shape a derivation walks",
                    },
                );
                labels.extend(secondary(signature, "the signature of the member".to_owned()));
                labels
            }
            Error::DerivationBindingMissing(binding, _, span) => {
                primary(span, &format!("this derivation has no `{}`", binding))
            }
            Error::DerivationBindingUnexpected(binding, _, _, span) => {
                primary(span, &format!("`{}` is not taken here", binding))
            }
            Error::DerivationBindingRepeated(binding, _, span, first) => {
                let mut labels = primary(span, &format!("`{}` is defined a second time here", binding));
                labels.extend(secondary(first, format!("`{}` is first defined here", binding)));
                labels
            }
            Error::DerivationBindingTakesTooMany(_, _, most, span) => primary(
                span,
                &format!("more than the {} the walk supplies", parameter_count(*most)),
            ),
            Error::DerivationIncomplete(_, left_out, span) => primary(
                span,
                &format!("no derivation for {}", name_list(left_out)),
            ),
            Error::DerivedInstanceNotDerivable(class, span) => primary(
                span,
                &format!("`{}` does not say how it is derived", class),
            ),
            Error::DerivedInstanceNoShape(_, span) => primary(span, "nothing to walk"),
            Error::DerivedInstanceContextTooNarrow(gap, context, derived) => {
                let mut labels = primary(
                    context,
                    &format!("this context does not provide `{}`", gap.missing),
                );
                labels.extend(secondary(
                    derived,
                    format!("the derivation needs `{}`", gap.missing),
                ));
                labels
            }
            Error::DerivedInstanceRequires(requirement, span) => {
                let mut labels = primary(
                    span,
                    &format!("this instance needs `{}` of `{}`", requirement.class, requirement.missing),
                );
                labels.extend(
                    requirement
                        .declared
                        .label("the type is declared here".to_owned()),
                );
                labels
            }
            Error::TypeArityMismatch(name, declared, written, span) => primary(
                span,
                &format!(
                    "`{}` takes {}, this application has {}",
                    name,
                    type_argument_count(*declared),
                    type_argument_count(*written)
                ),
            ),
            Error::TypeNotFound(_, span) => primary(span, "no type of this name is in scope"),
            Error::InvalidVariant(kind, span) => primary(
                span,
                match kind {
                    InvalidVariantKind::LowercaseName(_) => "this begins with a lowercase letter",
                    InvalidVariantKind::Tuple => "a tuple type, written where a variant belongs",
                    InvalidVariantKind::Unit => "the unit type, written where a variant belongs",
                    InvalidVariantKind::Arrow => "a function type, written where a variant belongs",
                    InvalidVariantKind::Record => "a record type, written where a variant belongs",
                },
            ),
            Error::InvalidScalarDeclaration(name, span) => primary(
                span,
                &format!(
                    "an opaque scalar's body must be exactly `{}`, with no other variant and no arguments",
                    name.unqualified_name()
                ),
            ),
            Error::InvalidConstraint(kind, span) => primary(
                span,
                match kind {
                    InvalidConstraintKind::Variable(_) => {
                        "a type variable, written where a constraint belongs"
                    }
                    InvalidConstraintKind::Unapplied(_) => {
                        "a name with no argument, written where a constraint belongs"
                    }
                    InvalidConstraintKind::Arrow => {
                        "a function type, written where a constraint belongs"
                    }
                    InvalidConstraintKind::Tuple => "a tuple, written where a constraint belongs",
                    InvalidConstraintKind::Unit => {
                        "the unit type, written where a constraint belongs"
                    }
                    InvalidConstraintKind::Record => {
                        "a record type, written where a constraint belongs"
                    }
                },
            ),
            Error::RepeatedLabel(label, _, repeat, first) => {
                let mut labels = primary(repeat, &format!("`{}` is given a second time here", label));
                if let Some(span) = first.span() {
                    labels.push(SpanLabel {
                        span,
                        message: format!("`{}` is first given here", label),
                        primary: false,
                        file: None,
                    });
                }
                labels
            }
            Error::InfixDeclared(_, span) => primary(span, "declared here"),
            Error::TypeDeclared(_, span) => primary(span, "declared here"),
            Error::ClassDeclared(span) => primary(span, "declared here"),
            Error::InstanceDeclared(span) => primary(span, "declared here"),
            Error::NoTypeInBinding(_, span) => primary(span, "declared here"),
            Error::UnsafeOutsideFacade(_, span) => primary(span, "marked `unsafe` here"),
            Error::FacadeTypeNotAdmitted(_, kind, span) => primary(
                span,
                match kind {
                    FacadeRejectedKind::Variable => "this signature names a type variable",
                    FacadeRejectedKind::Function => "this signature names a function type",
                },
            ),
            Error::FacadeResultNotEffect(_, span) => {
                primary(span, "this signature must return `Task (Result Failure a)`")
            }
            Error::FacadeTaskMisplaced(_, span) => primary(
                span,
                "this signature names `Task` outside the one position it may occupy",
            ),
            Error::FacadeConstrained(_, span) => primary(span, "a constraint on a facade signature"),
            Error::SelfDependency(members) => members
                .iter()
                .enumerate()
                .filter_map(|(i, member)| {
                    let name = &member.name;
                    let message = if members.len() == 1 {
                        format!("`{}` refers to its own value here", name)
                    } else if i == 0 {
                        format!(
                            "`{}` depends on itself through the declarations it mentions",
                            name
                        )
                    } else if member.function {
                        format!("the function `{}` is also part of the cycle", name)
                    } else {
                        format!("`{}` is also part of the cycle", name)
                    };

                    member.span.span().map(|s| SpanLabel {
                        span: s,
                        message,
                        primary: i == 0,
                        file: None,
                    })
                })
                .collect(),
            // A group has no position of its own; the errors it swallowed do.
            Error::EnvironmentErrors(errors) => errors.iter().flat_map(|e| e.labels()).collect(),
            Error::Many(errors) => errors.iter().flat_map(|e| e.labels()).collect(),
            _ => Vec::new(),
        }
    }

    fn notes(&self) -> Vec<String> {
        match self {
            Error::UnsafeOutsideFacade(..) => vec![
                "`unsafe` asserts that the companion behind a facade signature is a function of its arguments and that it returns"
                    .to_owned(),
            ],
            Error::FacadeTypeNotAdmitted(..) => vec![
                "a facade signature may only name a type whose values a target can decide from the value alone, which admits the primitives, tuples, records and union types applied to admitted types"
                    .to_owned(),
            ],
            Error::InvalidConstraint(..) => vec![
                "a constraint is a class name followed by the type it constrains, as in `Comparable a`, and several are written in parentheses separated by commas, as in `(Comparable k, Eq v)`"
                    .to_owned(),
            ],
            Error::FacadeResultNotEffect(..) => vec![
                "a facade declares an effect unless its signature is marked `unsafe`, and an effectful facade's result type must be exactly `Task (Result Failure a)` — any other result type needs `unsafe` to write"
                    .to_owned(),
            ],
            Error::FacadeTaskMisplaced(..) => vec![
                "`Task` may appear only as the whole of an unmarked facade's result type — not as an argument, and not nested inside another type"
                    .to_owned(),
            ],
            Error::FacadeConstrained(..) => vec![
                "a facade signature names the types the code behind it really handles, so the constraint belongs on an ordinary function that calls the facade at those types"
                    .to_owned(),
            ],
            Error::InvalidScalarDeclaration(..) => vec![
                "nothing in the language constructs or inspects a value of an opaque scalar, so its declaration exists to be read rather than built from"
                    .to_owned(),
            ],
            Error::OrphanInstance(..) => vec![
                "where neither the class nor the type is declared in this module, a type of this module's own that wraps the one wanted can be given the instance"
                    .to_owned(),
            ],
            Error::AmbiguousVariables(_, candidates, _)
            | Error::AmbiguousVariants(_, candidates, _) => vec![ambiguous_note(candidates)],
            // A group renders as a summary, so every message it swallowed becomes a
            // note. A group of one is rendered by its own message and adds nothing.
            Error::EnvironmentErrors(errors) => match errors.as_slice() {
                [only] => only.notes(),
                many => many.iter().flat_map(|e| e.message_and_notes()).collect(),
            },
            Error::Many(errors) => match errors.as_slice() {
                [only] => only.notes(),
                many => many.iter().flat_map(|e| e.message_and_notes()).collect(),
            },
            _ => Vec::new(),
        }
    }
}

/// 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`). Mirrors the identically-named helper
/// in `environment.rs`; kept separate rather than shared because the two
/// modules' `EnvError`/`Error` types are unrelated and neither should reach
/// into the other for a two-line formatter.
fn suggestion_suffix(suggestion: &Option<Name>) -> String {
    match suggestion {
        Some(name) => format!(" — did you mean `{}`?", name),
        None => String::new(),
    }
}

/// The `it is exposed by: …` note shared by `Error::AmbiguousVariables` and
/// `Error::AmbiguousVariants` — one clause for the contributors the module wrote
/// an `import` for, one for those supplied by [the default import
/// list](../../docs/spec/modules.md#the-default-imports) because it wrote
/// none. Naming the latter as implicit is what removes the surprise a module can
/// otherwise get from colliding with an import it never wrote (`SPEC-32`).
///
/// Every candidate this ever runs over comes from `ValueType::Foreigns`, so
/// `written`/`implicit` are never both empty in practice — `Foreigns` has at
/// least two entries and each is one or the other — but the match is written to
/// say something sensible even if that stopped holding.
fn ambiguous_note(candidates: &[(ModuleName, Option<super::SourceSpan>, ImportOrigin)]) -> String {
    let name_of =
        |(m, _, _): &(ModuleName, Option<super::SourceSpan>, ImportOrigin)| m.name().to_string();
    let written: Vec<String> = candidates
        .iter()
        .filter(|(_, _, origin)| *origin == ImportOrigin::Written)
        .map(name_of)
        .collect();
    let implicit: Vec<String> = candidates
        .iter()
        .filter(|(_, _, origin)| *origin == ImportOrigin::Default)
        .map(name_of)
        .collect();

    match (written.is_empty(), implicit.is_empty()) {
        (false, true) => format!("it is exposed by: {}", written.join(", ")),
        (true, false) => format!("it is exposed implicitly by: {}", implicit.join(", ")),
        (true, true) => "it is exposed by nothing this module can see".to_owned(),
        (false, false) => format!(
            "it is exposed by: {}, and implicitly by {}",
            written.join(", "),
            implicit.join(", ")
        ),
    }
}

/// "1 type argument" or "N type arguments" — the two counts an
/// `Error::TypeArityMismatch` message quotes.
fn type_argument_count(n: usize) -> String {
    if n == 1 {
        "1 type argument".to_owned()
    } else {
        format!("{} type arguments", n)
    }
}

/// "no parameters", "1 parameter" or "N parameters": what a derivation's binding may take.
fn parameter_count(n: usize) -> String {
    match n {
        0 => "no parameters".to_owned(),
        1 => "1 parameter".to_owned(),
        n => format!("{} parameters", n),
    }
}

/// The names of `names`, each in backticks, joined as a sentence does: `a`, `b` and `c`.
fn name_list(names: &[Name]) -> String {
    let quoted: Vec<String> = names.iter().map(|name| format!("`{}`", name)).collect();

    match quoted.split_last() {
        None => String::new(),
        Some((only, [])) => only.clone(),
        Some((last, rest)) => format!("{} and {}", rest.join(", "), last),
    }
}

/// How a name is exposed, said in the words the source uses for it.
fn export_type_noun(tpe: &ExportType) -> &'static str {
    match tpe {
        ExportType::Value => "value",
        ExportType::Infix => "infix operator",
        ExportType::UnionPublic | ExportType::UnionPrivate => "type",
        ExportType::Class => "class",
    }
}

impl From<Vec<EnvError>> for Error {
    fn from(errors: Vec<EnvError>) -> Self {
        Error::EnvironmentErrors(errors)
    }
}

impl From<Vec<Error>> for Error {
    fn from(errors: Vec<Error>) -> Self {
        Error::Many(errors)
    }
}

/// Every piece of a facade signature [`check_facade_admitted_type`] walks: its
/// parameters and its result, the top-level `Arrow`s separating them stripped
/// away first. A facade is itself a function, so those are the one place an
/// arrow is admitted — a parameter or a result that is itself a function type
/// is what [`check_facade_admitted_type`] then rejects. A facade constant has
/// no top-level arrow to strip, so it is returned whole, as its own one piece.
fn facade_signature_pieces(tpe: &Type) -> Vec<&Type> {
    match tpe {
        Type::Arrow(param, rest) => {
            let mut pieces = vec![param.as_ref()];
            pieces.extend(facade_signature_pieces(rest));
            pieces
        }
        _ => vec![tpe],
    }
}

/// Whether `tpe` — one piece of a facade signature, as
/// [`facade_signature_pieces`] cuts it up — is one of [the admitted
/// types](../../docs/spec/interop.md#which-types-may-cross-the-boundary).
///
/// A bare `Type::Variable` or a `Type::Arrow` anywhere inside `tpe` is
/// rejected, the latter regardless of depth — a function type is inadmissible
/// wherever it is found, not only at the top of the signature.
/// `Type::Type`, `Type::Tuple` and `Type::Record` recurse into their own arguments or
/// fields, which may still hide either form. `Type::Unit` is admitted: it has one
/// value, and the table gives it a predicate like any other admitted type.
fn check_facade_admitted_type(tpe: &Type) -> Result<(), FacadeRejectedKind> {
    match tpe {
        Type::Variable(_) => Err(FacadeRejectedKind::Variable),
        Type::Arrow(_, _) => Err(FacadeRejectedKind::Function),
        Type::Type(_, args) => args.iter().try_for_each(check_facade_admitted_type),
        Type::Tuple(tuple) => tuple.iter().try_for_each(check_facade_admitted_type),
        Type::Record(fields) => fields.values().try_for_each(check_facade_admitted_type),
        Type::Unit => Ok(()),
    }
}

/// Whether `name` is the declaration `module` of `zelkova-core` writes `item`
/// as — `is_core_declaration(name, "Task", "Failure")` for `Task.Failure`.
///
/// All three parts have to match, the same way [`scalars::Scalar::declares`]
/// recognises a scalar: a module named `Task` can only belong to
/// `zelkova-core` ([`default_imports`](super::default_imports)'s doc comment
/// says why), so this is what keeps a package's own `Task` module — were one
/// ever allowed — or a differently-named module's own `Task` type from being
/// misread as the one [`Error::FacadeResultNotEffect`] and
/// [`Error::FacadeTaskMisplaced`] care about.
fn is_core_declaration(name: &QualName, module: &str, item: &str) -> bool {
    name.package().as_str() == CORE_PACKAGE
        && name.module_name().as_str() == module
        && name.unqualified_name().as_str() == item
}

/// Whether `name` is `Task.Task`'s declaration.
fn is_task_declaration(name: &QualName) -> bool {
    is_core_declaration(name, "Task", "Task")
}

/// Whether `name` is `Result.Result`'s declaration.
fn is_result_declaration(name: &QualName) -> bool {
    is_core_declaration(name, "Result", "Result")
}

/// Whether `name` is `Task.Failure`'s declaration.
fn is_failure_declaration(name: &QualName) -> bool {
    is_core_declaration(name, "Task", "Failure")
}

/// Whether `Task` — recognised by [`is_task_declaration`], never by spelling —
/// appears anywhere inside `tpe`, at the top or nested inside a tuple, a record's
/// fields or another type's arguments.
///
/// What [`Error::FacadeTaskMisplaced`] is raised from: `Task` may appear only
/// as the whole of an unmarked facade's result
/// (`docs/spec/interop.md#an-effectful-facade`), so every other piece of a
/// facade signature, and the payload inside an accepted `Task (Result Failure
/// a)` result, is walked with this rather than left to
/// [`check_facade_admitted_type`], which does not know `Task` from any other
/// union.
fn contains_task(tpe: &Type) -> bool {
    match tpe {
        Type::Type(name, args) => is_task_declaration(name) || args.iter().any(contains_task),
        Type::Tuple(tuple) => tuple.iter().any(contains_task),
        Type::Record(fields) => fields.values().any(contains_task),
        Type::Arrow(param, rest) => contains_task(param) || contains_task(rest),
        Type::Variable(_) | Type::Unit => false,
    }
}

/// Whether `tpe`'s own outermost constructor is `Task` — true of `Task Int`
/// and of `Task (Result Failure a)` alike, and false of `Maybe (Task Int)`,
/// where `Task` is present but not in that position.
///
/// [`effectful_result_payload`] tells the two admitted shapes apart; this is
/// what lets the caller tell "the right shape with the wrong contents" apart
/// from "`Task` in a position that was never going to be it", which is what
/// distinguishes [`Error::FacadeResultNotEffect`] from
/// [`Error::FacadeTaskMisplaced`].
fn is_task_applied(tpe: &Type) -> bool {
    matches!(tpe, Type::Type(name, _) if is_task_declaration(name))
}

/// The payload `a` of `tpe`, when `tpe` is exactly the shape an unmarked
/// facade's result must be — `Task (Result Failure a)`, `Task`, `Result` and
/// `Failure` each recognised by the qualified name of their declaration and
/// never by spelling. `None` for any other shape, `Task Int` and
/// `Maybe (Task Int)` included — those are [`Error::FacadeResultNotEffect`],
/// not this function's business to name.
pub fn effectful_result_payload(tpe: &Type) -> Option<&Type> {
    let Type::Type(task, task_args) = tpe else {
        return None;
    };
    if !is_task_declaration(task) {
        return None;
    }
    let [result_tpe] = task_args.as_slice() else {
        return None;
    };
    let Type::Type(result, result_args) = result_tpe else {
        return None;
    };
    if !is_result_declaration(result) {
        return None;
    }
    let [failure_tpe, payload] = result_args.as_slice() else {
        return None;
    };
    let Type::Type(failure, failure_args) = failure_tpe else {
        return None;
    };
    if !is_failure_declaration(failure) || !failure_args.is_empty() {
        return None;
    }
    Some(payload)
}

/// Hold a facade signature `function`, whose type canonicalized to `tpe`, to what a
/// facade may declare: every piece one of the admitted types, `Task` nowhere but the
/// whole of an unmarked signature's result, and that result exactly
/// `Task (Result Failure a)` unless the signature is `unsafe`.
///
/// The first rule a signature breaks is its error. One bad signature does not hide the
/// next: the caller records this one as broken and goes on to the next.
fn check_facade_signature(function: &parser::Function, tpe: &Type) -> Result<(), Error> {
    // Every parameter and the result — the arrows a facade's own
    // parameter list contributes stripped first, since a facade is
    // itself a function and that is the one place an arrow is
    // admitted — must be one of the admitted types
    // (`docs/spec/interop.md#which-types-may-cross-the-boundary`).
    // Walked once and reused below for the `Task`-placement check.
    let pieces = facade_signature_pieces(tpe);
    if let Some(kind) = pieces
        .iter()
        .copied()
        .find_map(|piece| check_facade_admitted_type(piece).err())
    {
        return Err(Error::FacadeTypeNotAdmitted(
            function.name.clone(),
            kind,
            function.annotation_span,
        ));
    }

    // `Task` is confined to the whole of an unmarked facade's result
    // (`docs/spec/interop.md#an-effectful-facade`), so a parameter
    // piece may never hold one, whether or not the signature is
    // `unsafe`. Reached only once the loop above admits every piece,
    // so nothing here still hides a bare type variable or function
    // type for `contains_task` to misread.
    if let Some((&result, parameters)) = pieces.split_last() {
        if parameters.iter().copied().any(contains_task) {
            return Err(Error::FacadeTaskMisplaced(
                function.name.clone(),
                function.annotation_span,
            ));
        }

        // The result is held to the required effect shape unless the
        // signature says `unsafe` (`DEC-12` decision 1 and 7): an
        // unmarked facade's result must be exactly
        // `Task (Result Failure a)`, and `unsafe` is what removes that
        // requirement rather than any shape `check_facade_admitted_type`
        // already accepted. `Task` still may not appear anywhere else —
        // nested in the payload `a` above, nested under some other type
        // (`Maybe (Task Int)`), or anywhere at all in an `unsafe`
        // facade's result, which gets no exemption from this.
        //
        // `is_task_applied(result)` tells "the right shape with the
        // wrong contents" (`Task Int`) apart from "`Task` in a position
        // that was never going to be it" (`Maybe (Task Int)`), which is
        // what keeps the two error variants pointed at what each is
        // actually about.
        if function.marked_unsafe {
            if contains_task(result) {
                return Err(Error::FacadeTaskMisplaced(
                    function.name.clone(),
                    function.annotation_span,
                ));
            }
        } else if is_task_applied(result) {
            match effectful_result_payload(result) {
                Some(payload) if contains_task(payload) => {
                    return Err(Error::FacadeTaskMisplaced(
                        function.name.clone(),
                        function.annotation_span,
                    ));
                }
                Some(_) => {}
                None => {
                    return Err(Error::FacadeResultNotEffect(
                        function.name.clone(),
                        function.annotation_span,
                    ))
                }
            }
        } else if contains_task(result) {
            return Err(Error::FacadeTaskMisplaced(
                function.name.clone(),
                function.annotation_span,
            ));
        } else {
            return Err(Error::FacadeResultNotEffect(
                function.name.clone(),
                function.annotation_span,
            ));
        }
    }

    Ok(())
}

/// Check that every element of `context` — what an annotation wrote in front of
/// `=>`, already split into a list by the parser — is shaped like a constraint,
/// and hand back each constraint's class name and arguments.
///
/// A constraint here is an uppercase name applied to one or more arguments.
/// Nothing is resolved here: whether the name is a class, and whether its arguments
/// are types in scope, is not checked. A class head's, an instance's and an
/// annotation's constraints are resolved afterwards, by `classes::constraints`; a
/// facade signature's are not resolved at all. The list may be of any length. Every
/// malformed element is reported, each at its own span.
fn validate_context(
    context: &parser::Context,
) -> Result<Vec<(&Name, &[parser::Type])>, Vec<Error>> {
    collect_accumulate(context.constraints.iter().map(|constraint| {
        let kind = match &constraint.kind {
            parser::TypeKind::Unqualified(class, args) if !args.is_empty() => {
                return Ok((class, args.as_slice()));
            }
            parser::TypeKind::Unqualified(name, _) => {
                InvalidConstraintKind::Unapplied(name.clone())
            }
            parser::TypeKind::Variable(name) => InvalidConstraintKind::Variable(name.clone()),
            parser::TypeKind::Arrow(..) => InvalidConstraintKind::Arrow,
            parser::TypeKind::Tuple(..) => InvalidConstraintKind::Tuple,
            parser::TypeKind::Unit => InvalidConstraintKind::Unit,
            parser::TypeKind::Record(..) => InvalidConstraintKind::Record,
        };

        Err(Error::InvalidConstraint(kind, constraint.span))
    }))
}

/// Transform a given `parser::Module` into a `canonical::Module`, or into the errors
/// that kept it from being one.
///
/// [`canonicalize_recovering`], reduced to all-or-nothing: a module that came back with
/// errors is `Err` with all of them.
pub fn canonicalize(
    package: &PackageName,
    interfaces: &HashMap<Name, Interface>,
    source: &parser::Module,
) -> Result<Module, Vec<Error>> {
    let Canonicalized { module, errors } = canonicalize_recovering(package, interfaces, source);

    if errors.is_empty() {
        Ok(module)
    } else {
        Err(errors)
    }
}

/// Transform a given `parser::Module` into a `canonical::Module`, and hand it back
/// beside every error found on the way.
///
/// There is always a module. An import that does not resolve is reported as one
/// [`Error::EnvironmentErrors`] and costs the module that import and nothing else. A
/// declaration that does not canonicalize costs the module that declaration and nothing
/// else. A value declaration is recorded in [`Module::broken`], with its annotation when
/// that canonicalized; a `type`, `infix`, `class` or `instance` declaration is left out of
/// [`Module::types`], [`Module::infixes`], [`Module::classes`] or [`Module::instances`]. An
/// `exposing` entry that does not resolve is left out of [`Module::exports`].
///
/// # Declarations that failed to parse
///
/// `source` may be a module that parsed only in part ([`parser::Module::failed`]), and
/// each declaration chunk that failed has already been reported as a syntax error. A chunk
/// that names a value puts that name in scope, so a reference to it resolves, and the
/// value is recorded in [`Module::broken`] with no error of its own: its annotation, when
/// one parsed, is read and checked as any other's, and nothing else of it is. A chunk that
/// names nothing makes the scope incomplete before the first sub-pass runs ([`DEC-23`
/// decision
/// 4](../../../docs/decisions/dec-23.md#4--one-name-is-read-off-a-failed-chunk-a-values)).
///
/// # Incomplete scopes
///
/// A scope is [incomplete](Module::incomplete) when a name could be missing from it for
/// a reason already reported, and a not-found error raised in one is dropped
/// ([`DEC-23` decision
/// 3](../../../docs/decisions/dec-23.md#3--an-error-that-restates-a-reported-failure-is-dropped-by-a-flag-on-the-scope)).
/// Each sub-pass's errors are filtered by the flag as it stood **before** that sub-pass
/// ran: a declaration's own failure is reported, and what it makes incomplete is
/// everything after it. A failed `infix` declaration makes the scope incomplete for
/// everything after the infixes, a failed `type` declaration for everything after the
/// types, a failed `class` declaration for the values, the bindings of the classes and
/// the instances, and the `exposing` list, a derivation that failed its checks for the
/// instances, and the `exposing` list, and a failed `instance` declaration for the
/// `exposing` list. Dropping an error does not make
/// its declaration sound. A declaration the dropped error broke is left out all the same;
/// one whose only error was a name that did not resolve stays in [`Module::values`] holding
/// a hole ([`ExpressionKind::Hole`], [`PatternKind::Hole`]) for it, which no backend emits
/// and [`Value::holds_hole`] finds.
///
/// Whether this module is exempt from the default imports is not this function's
/// question to answer: `new_environment` derives it from `package` itself
/// ([`PackageName::is_core`]) once `name` is built.
pub fn canonicalize_recovering(
    package: &PackageName,
    interfaces: &HashMap<Name, Interface>,
    source: &parser::Module,
) -> Canonicalized {
    let name = ModuleName {
        package: package.clone(),
        name: source.name.clone(),
    };

    let mut errors: Vec<Error> = vec![];
    let (mut env, import_errors) = new_environment(&name, interfaces, &source.imports);
    if !import_errors.is_empty() {
        // Reported whole, and never filtered: this is the failure everything else
        // in an incomplete scope restates.
        errors.push(import_errors.into());
    }

    // A declaration that failed to parse has already been reported as a syntax error.
    // One that names a value puts the name in scope, so a reference to it resolves, and
    // the value is broken below with no error of its own. One that names nothing could
    // have declared any name at all, so the scope is incomplete from the first sub-pass
    // on ([`DEC-23` decision
    // 4](../../../docs/decisions/dec-23.md#4--one-name-is-read-off-a-failed-chunk-a-values)).
    let unparsed = unparsed_values(source);
    for name in unparsed.keys() {
        env.insert_top_level_value(name.clone());
    }
    if source.failed.iter().any(|failed| failed.declares.is_none()) {
        env.set_incomplete();
    }

    // `unsafe` is a claim about the companion standing behind a facade signature,
    // so it has nothing to say on a declaration with a body above it. The grammar
    // accepts the word on any annotation — it has no way to know the module's
    // header — which leaves this as the only place that can reject one. Reported
    // for every marked declaration, then canonicalization carries on, so a module
    // with a stray `unsafe` still reports whatever else is wrong with it.
    if !source.binding_foreign {
        errors.extend(
            source
                .functions
                .iter()
                .filter(|f| f.marked_unsafe)
                .map(|f| Error::UnsafeOutsideFacade(f.name.clone(), f.annotation_span)),
        );
    }

    // A facade signature's context is checked for its shape and rejected here, and is
    // not resolved: a facade takes no constraint, so the classes it names do not matter.
    // Every other module's annotation context is resolved with the annotation, in
    // `annotation`, and kept on the canonical value beside the type
    // (`Value::TypedValue::context`, `Broken::context`), from where `to_interface`
    // publishes it. The type checker reads only the type after `=>`.
    if source.binding_foreign {
        for function in source.functions.iter() {
            if let Some(context) = &function.context {
                if let Err(malformed) = validate_context(context) {
                    errors.extend(malformed);
                }

                errors.push(Error::FacadeConstrained(
                    function.name.clone(),
                    context.span,
                ));
            }
        }
    }

    let (infixes, types, classes, instances, values, mut broken) = if source.binding_foreign {
        // A `module foreign` facade runs a parallel canonicalization process as the constraints are a bit different:
        // - Only functions without bindings are authorized.
        // - Infixes and types are forbidden.
        // The idea being to have the facade stand for the companion file shipped beside it.
        // Assuming Json types are part of the prelude, this should goes well with the restriction on what types are available for bindings.

        // Verify no infix present
        if !source.infixes.is_empty() {
            let e = source
                .infixes
                .iter()
                .map(|i| Error::InfixDeclared(i.operator.clone(), i.span));
            errors.extend(e);
        }
        // Verify no types present
        if !source.types.is_empty() {
            let e = source
                .types
                .iter()
                .map(|t| Error::TypeDeclared(t.name.clone(), t.span));
            errors.extend(e);
        }
        // Nor classes and instances: a facade holds signatures only.
        errors.extend(
            source
                .classes
                .iter()
                .map(|class| Error::ClassDeclared(class.span)),
        );
        errors.extend(
            source
                .instances
                .iter()
                .map(|instance| Error::InstanceDeclared(instance.span)),
        );

        // Register each binding as a top-level value before resolving any of
        // them, the same as the non-`foreign` branch below — otherwise
        // `do_exports`'s existence check (`BUG-8`) would reject a facade
        // exposing its own declared binding, since nothing would have told
        // `env` the binding exists.
        for f in source.functions.iter() {
            env.insert_top_level_value(f.name.clone());
        }

        // Iterate on values. A signature that is rejected is recorded as broken, with
        // its type when that canonicalized.
        let iter = source.functions.iter().map(|function| {
            let tpe = function
                .tpe
                .as_ref()
                .map(|tpe| Type::from_parser_type(&env, tpe));

            // A declaration a failed chunk names is broken whatever parsed of it, and
            // only its annotation, when one parsed, is checked: a missing signature or
            // a binding beside it may be the chunk that failed.
            if let Some(chunk) = unparsed.get(&function.name) {
                return Err(match tpe {
                    Some(Ok(tpe)) => {
                        let errors = check_facade_signature(function, &tpe).err();
                        Rejected::unparsed(
                            function,
                            Some((tpe, Vec::new())),
                            errors.into_iter().collect(),
                            *chunk,
                        )
                    }
                    Some(Err(error)) => Rejected::unparsed(function, None, vec![error], *chunk),
                    None => Rejected::unparsed(function, None, vec![], *chunk),
                });
            }

            // Make sure there is no binding
            if !function.bindings.is_empty() {
                // The signature's own error is reported too, as `do_values` does for a
                // body beside a failed annotation: the annotation's first, then the
                // binding's. A missing signature is that error as well.
                // TODO More specific error
                let binding = Error::BindingPatternsInvalidLen(function.span);
                return Err(match tpe {
                    Some(Ok(tpe)) => {
                        Rejected::new(function, Some((tpe, Vec::new())), vec![binding])
                    }
                    Some(Err(error)) => Rejected::new(function, None, vec![error, binding]),
                    None => Rejected::new(
                        function,
                        None,
                        vec![
                            Error::NoTypeInBinding(function.name.clone(), function.span),
                            binding,
                        ],
                    ),
                });
            }

            // Make sure there is a type
            let tpe = match tpe {
                Some(Ok(tpe)) => tpe,
                Some(Err(error)) => return Err(Rejected::new(function, None, vec![error])),
                None => {
                    return Err(Rejected::new(
                        function,
                        None,
                        vec![Error::NoTypeInBinding(function.name.clone(), function.span)],
                    ))
                }
            };

            match check_facade_signature(function, &tpe) {
                Ok(()) => {}
                Err(error) => {
                    return Err(Rejected::new(
                        function,
                        Some((tpe, Vec::new())),
                        vec![error],
                    ))
                }
            }

            let name = function.name.clone();
            // TODO Think how it's going to be represented. Currently canonical values assume an expression is present
            //      I'd like to not introduce a trait or new struct for binding. Should we fake an expression or create
            //      a new type of value ? New type of value will be annoying for regular modules as they aren't present
            //      there. Fake expression might be ok as MVP. We have to make sure that binding module are removed from
            //      some phase of the compilation pipeline.
            let value = Value::TypedValue {
                name: name.clone(),
                patterns: vec![],
                // A `module foreign` facade has no body in the source, so this
                // stand-in has nothing to point at (see the TODO above).
                body: Expression::bare(ExpressionKind::Unit),
                tpe,
                // A facade's context is `FacadeConstrained`, reported above.
                context: Vec::new(),
                marked_unsafe: function.marked_unsafe,
                span: function.span,
                annotation_span: function.annotation_span,
            };

            Ok((name, value))
        });
        let (values, rejected): (HashMap<Name, Value>, Vec<Box<Rejected>>) = collect_partial(iter);
        let (broken, rejected_errors) = Rejected::split(rejected);
        errors.extend(without_restated(rejected_errors, env.is_incomplete()));

        (
            HashMap::new(),
            HashMap::new(),
            HashMap::new(),
            Vec::new(),
            values,
            broken,
        )
    } else {
        // Because we are rewriting infixes in this phase, we must do this check before
        // resolving values.
        //
        // Each sub-pass below has its errors filtered by whether the scope was
        // incomplete when the sub-pass *started* (`without_restated`): the failure of a
        // declaration is reported, and what it makes incomplete is what comes after it.
        // A class member is a top-level value of this module, which is what lets an
        // `infix` declaration name one.
        let members: Vec<(&Name, &Name, NodeSpan)> = source
            .classes
            .iter()
            .filter_map(|class| match &class.head.kind {
                parser::TypeKind::Unqualified(name, _) => Some((name, class)),
                _ => None,
            })
            .flat_map(|(class_name, class)| {
                classes::member_names(class).map(move |(member, span)| (member, class_name, span))
            })
            .collect();

        let incomplete = env.is_incomplete();
        let (infixes, infix_errors) = do_infixes(
            &source.infixes,
            &mut env,
            &source.functions,
            &members,
            &unparsed,
        );
        if !infix_errors.is_empty() {
            // The operator the declaration would have named is missing from the scope.
            env.set_incomplete();
        }
        errors.extend(without_restated(infix_errors, incomplete));

        // Every `type` declaration of this module is in scope for every one of
        // them, its own body included, so all of their names are registered
        // before any body is canonicalized. Doing it as `do_types` produced each
        // union instead would make a declaration resolvable only from the ones
        // written below it, and leave a self-referential declaration —
        // `type Never = JustOneMore Never` — naming a type nothing has heard of.
        // The name and its arity are all a use site needs; `insert_union_type`
        // below fills the constructors in once the bodies are built.
        for tpe in source.types.iter() {
            env.insert_declared_type(&tpe.name, tpe.type_arguments.clone());
        }

        let incomplete = env.is_incomplete();
        let (types, type_errors) = do_types(&env, &source.types);
        if !type_errors.is_empty() {
            // The constructors the declaration would have named are missing from the
            // scope, and so is the type from the interface.
            env.set_incomplete();
        }
        errors.extend(without_restated(type_errors, incomplete));

        for (n, t) in types.iter() {
            env.insert_union_type(n.clone(), t.clone());
        }

        trace!("Environment after do_types: {:#?}", env);

        // Every class name is registered before any class is read, so a superclass or an
        // instance can name one written further down the file. A class that fails leaves
        // its members, and the instances of it, missing from the scope.
        let incomplete = env.is_incomplete();
        let (declared, mut class_errors) =
            classes::declare_classes(&mut env, &source.classes, &source.types);
        let mut signatures = Vec::new();
        for (index, name, variable) in declared {
            let class = &source.classes[index];
            match classes::class_signature(&env, class, name, variable) {
                Ok(signature) => {
                    env.insert_class_signature(name, signature.clone());
                    signatures.push((class, name, signature));
                }
                Err(errors) => class_errors.extend(errors),
            }
        }
        if !class_errors.is_empty() {
            env.set_incomplete();
        }
        errors.extend(without_restated(class_errors, incomplete));
        // A member and a value sharing a name leave neither missing from the scope.
        errors.extend(member_clashes(&members, &source.functions, &unparsed));

        for (member, _, _) in members.iter() {
            env.insert_top_level_value((*member).clone());
        }

        // TODO Should I manage infixes rewrite here too ?
        // Yes I should do it here
        let incomplete = env.is_incomplete();
        let Values {
            values,
            broken,
            errors: value_errors,
        } = do_values(&mut env, &source.functions, &unparsed);
        errors.extend(without_restated(value_errors, incomplete));

        // A derivation's bindings and an instance's are ordinary values, and may name
        // any value of the module, so they are read once every value is in scope.
        let incomplete = env.is_incomplete();
        let mut unresolved = Vec::new();
        let mut derivation_errors = Vec::new();
        let mut canonical_classes = HashMap::new();
        for (class, name, mut signature) in signatures {
            let (derivations, errors) =
                derivation::class_derivations(&env, class, name, &signature, &mut unresolved);
            signature.derivations_rejected = !errors.is_empty();
            derivation_errors.extend(errors);
            signature.derivations = derivations;
            // An instance of the class, in this module, is read against the derivations.
            env.insert_class_signature(name, signature.clone());
            canonical_classes.insert(name.clone(), Class { signature });
        }
        // A failed derivation removes no name from the scope, so the scope stays as complete
        // as it was. The class carries that its derivations were rejected, which is what
        // keeps an instance asking to be derived from restating it.
        errors.extend(without_restated(derivation_errors, incomplete));

        let incomplete = env.is_incomplete();
        let mut binding_errors = Vec::new();
        let classes::Instances {
            instances,
            errors: instance_errors,
        } = classes::do_instances(&env, &source.instances, &mut unresolved);
        // An instance left out of the module is one an importer's scope will not have, and
        // some are left out with no error here: one of a class whose derivations were
        // rejected.
        if !instance_errors.is_empty() || instances.len() < source.instances.len() {
            env.set_incomplete();
        }
        binding_errors.extend(instance_errors);
        binding_errors.extend(unresolved);
        errors.extend(without_restated(binding_errors, incomplete));

        (infixes, types, canonical_classes, instances, values, broken)
    };

    // A value only a failed chunk declares has no `parser::Function` for either branch
    // to have read, and nothing of it to keep but where it was written.
    broken.extend(
        unparsed
            .iter()
            .filter(|(name, _)| !source.functions.iter().any(|f| &f.name == *name))
            .map(|(name, chunk)| Broken {
                name: name.clone(),
                span: *chunk,
                tpe: None,
                context: Vec::new(),
                annotation_span: NodeSpan::none(),
            }),
    );
    broken.sort_by(|left, right| left.name.as_str().cmp(right.name.as_str()));

    // A parameterless binding's value has to exist before it can be used, so a
    // cycle that holds one — through other bindings or through functions — is an
    // error (`docs/spec/evaluation-semantics.md#a-binding-may-not-depend-on-itself`).
    // Independent of exports, so this runs regardless of what `do_exports` below
    // finds.
    if let Err(err) = check_self_dependency(&values) {
        errors.extend(err);
    }

    // We do exports at the end, and verify that all exported value do
    // have a reference within the current module
    // A declaration that is broken and was written with no annotation is in neither
    // `values` nor `Broken::tpe`, so `do_exports` is told of it here: it is as exposed
    // and as unannotated as a sound `Value::Value`. A facade is left out: its unannotated
    // signature already is `NoTypeInBinding`. So is a declaration a failed chunk names,
    // whose annotation may be that chunk.
    let unannotated_broken: HashMap<Name, NodeSpan> = source
        .functions
        .iter()
        .filter(|f| {
            !source.binding_foreign
                && f.tpe.is_none()
                && !unparsed.contains_key(&f.name)
                && broken.iter().any(|b| b.name == f.name)
        })
        .map(|f| (f.name.clone(), f.span))
        .collect();
    let member_classes: HashMap<&Name, &Name> = classes
        .iter()
        .flat_map(|(class, c)| c.signature.members.iter().map(move |m| (&m.name, class)))
        .collect();
    let (exports, export_errors) = do_exports(
        &source.exposing,
        &env,
        &values,
        &unannotated_broken,
        &member_classes,
    );
    errors.extend(without_restated(export_errors, env.is_incomplete()));

    // A declaration written with an annotation that did not canonicalize is recorded
    // with no type, and the interface cannot publish it. That is a name missing from
    // the interface while this module's own scope is whole, so it is a case the
    // environment's flag does not already say. A declaration a failed chunk names and
    // that has no type is the other: its annotation may be the chunk that failed.
    let annotation_failed = source
        .functions
        .iter()
        .any(|f| f.tpe.is_some() && broken.iter().any(|b| b.name == f.name && b.tpe.is_none()))
        || broken
            .iter()
            .any(|b| b.tpe.is_none() && unparsed.contains_key(&b.name));

    Canonicalized {
        module: Module {
            name,
            exports,
            exposing_span: source.exposing_span,
            infixes,
            types,
            classes,
            instances,
            imported_instances: env.imported_instances().to_vec(),
            values,
            broken,
            binding_foreign: source.binding_foreign,
            incomplete: env.is_incomplete() || annotation_failed,
        },
        errors,
    }
}

/// Every value a declaration chunk of `source` that failed to parse names
/// ([`parser::Failed::declares`]), with where it was written: the chunk's text, or the
/// text of every chunk naming it merged.
fn unparsed_values(source: &parser::Module) -> HashMap<Name, NodeSpan> {
    let mut unparsed: HashMap<Name, NodeSpan> = HashMap::new();
    for failed in &source.failed {
        if let Some(name) = &failed.declares {
            let chunk = NodeSpan::new(failed.span.start, failed.span.end);
            let span = unparsed.entry(name.clone()).or_insert(chunk);
            *span = span.merge(chunk);
        }
    }
    unparsed
}

/// `errors` without the ones that only restate a failure already reported, when the scope
/// they were raised in is `incomplete`.
///
/// An incomplete scope is one where a name could be missing for a reason that has been
/// reported ([`Module::incomplete`]), so a name that is not found in it says nothing new:
/// `VariableNotFound`, `VariantNotFound`, `TypeNotFound`, `ClassNotFound`,
/// `ExportNotFound`, `InfixReferenceInvalidValue` and `MissingSuperclassInstance` are
/// dropped, and every other error is kept. An
/// [`Error::Many`] is flattened into its members first, so a group holding one of each
/// keeps the member that is not a restatement. With `incomplete` false, `errors` comes
/// back untouched.
///
/// `InfixReferenceInvalidValue` is on that list although it is raised in one place only,
/// for an `infix` declaration naming a function this module does not declare, and so
/// restates nothing today: in an incomplete scope it is deferred, and the failure that
/// made the scope incomplete stands in the build. It would restate one if a function that
/// failed were ever left out of that function list.
///
/// `MissingSuperclassInstance` is on it because an instance that failed is published by
/// no interface, so a superclass instance its module wrote and could not keep is missing
/// from every importer's scope, and the module that wrote it has already said why.
///
/// Dropping an error does not make its declaration sound. A declaration the error broke
/// has already been left out of the module by the caller, and stays left out; one whose
/// error was a name that did not resolve keeps the hole standing for it, which no backend
/// emits.
fn without_restated(errors: Vec<Error>, incomplete: bool) -> Vec<Error> {
    if !incomplete {
        return errors;
    }

    fn flatten(error: Error, into: &mut Vec<Error>) {
        match error {
            Error::Many(members) => members.into_iter().for_each(|member| flatten(member, into)),
            error => into.push(error),
        }
    }

    let mut flat = Vec::new();
    for error in errors {
        flatten(error, &mut flat);
    }

    flat.retain(|error| {
        !matches!(
            error,
            Error::VariableNotFound(..)
                | Error::VariantNotFound(..)
                | Error::TypeNotFound(..)
                | Error::ClassNotFound(..)
                | Error::ExportNotFound(..)
                | Error::InfixReferenceInvalidValue(..)
                | Error::MissingSuperclassInstance(..)
        )
    });
    flat
}

/// Whether `value` names no parameter — the kind of binding a cycle
/// [`check_self_dependency`] reports must hold, and the only kind
/// [`initialisation_order`] schedules. Both `Value` variants carry
/// their patterns under a different shape (`Vec<Pattern>` vs. `Vec<(Pattern,
/// Type)>`), so this is the one place that reaches past the difference to ask
/// how many there are.
fn is_parameterless(value: &Value) -> bool {
    match value {
        Value::Value { patterns, .. } => patterns.is_empty(),
        Value::TypedValue { patterns, .. } => patterns.is_empty(),
    }
}

/// Every `VarTopLevel` reference `expr` makes, walking every subexpression a
/// body can hold — a reference is a reference wherever it sits, including
/// inside a `case` branch or an `if` arm
/// (`docs/spec/evaluation-semantics.md#a-binding-may-not-depend-on-itself`).
///
/// `VarTopLevel` is the only expression kind this needs to look for: it is
/// what `Expression::from_parser`'s `Variable` arm produces for a name
/// `Environment::find_value` resolves to `ValueType::TopLevel`, which
/// `insert_top_level_value` sets only for a declaration of *this* module — a
/// local pattern binding resolves to `VarLocal` and an imported name to
/// `VarForeign`, neither of which this pass has any business following.
fn collect_top_level_refs(expr: &Expression, out: &mut Vec<Name>) {
    match &expr.kind {
        ExpressionKind::VarTopLevel(qual) => out.push(qual.unqualified_name()),
        ExpressionKind::VarLocal(_)
        | ExpressionKind::VarKernel(_)
        | ExpressionKind::VarForeign(_, _, _)
        | ExpressionKind::VarConstructor(_, _)
        | ExpressionKind::Char(_)
        | ExpressionKind::String(_)
        | ExpressionKind::Int(_)
        | ExpressionKind::Float(_)
        | ExpressionKind::Unit
        // A label names no declaration.
        | ExpressionKind::Accessor(_, _)
        // A name that did not resolve names no declaration of this module.
        | ExpressionKind::Hole => {}
        ExpressionKind::Access(record, _, _) => collect_top_level_refs(record, out),
        ExpressionKind::Apply(a, b) => {
            collect_top_level_refs(a, out);
            collect_top_level_refs(b, out);
        }
        ExpressionKind::If(cond, then, els) => {
            collect_top_level_refs(cond, out);
            collect_top_level_refs(then, out);
            collect_top_level_refs(els, out);
        }
        ExpressionKind::Case(scrutinee, branches) => {
            collect_top_level_refs(scrutinee, out);
            for branch in branches {
                collect_top_level_refs(&branch.expression, out);
            }
        }
        ExpressionKind::Tuple(tuple) => {
            for e in tuple.iter() {
                collect_top_level_refs(e, out);
            }
        }
        ExpressionKind::Record(fields) => {
            for field in fields {
                collect_top_level_refs(&field.value, out);
            }
        }
        ExpressionKind::Update(record, fields) => {
            collect_top_level_refs(record, out);
            for field in fields {
                collect_top_level_refs(&field.value, out);
            }
        }
    }
}

/// The graph *depends on* is read off: one node per top-level declaration of `values`,
/// functions included, and an edge from `u` to `v` for every [`collect_top_level_refs`]
/// reference `u`'s body makes to `v`. A binding depends on everything it can reach along
/// these edges ([evaluation
/// semantics](../../docs/spec/evaluation-semantics.md#a-binding-with-no-parameters-is-evaluated-once)):
/// initialising a binding runs its body and whatever functions that body calls, and a
/// function can only be called by code that names it or was handed it by code that did,
/// so what can run while a binding is initialised is contained in what it reaches. The
/// relation over-approximates — `a = f` beside `f x = a` mentions `f` without calling it —
/// and [`DEC-19`](../../docs/decisions/dec-19.md) is why that is the rule.
///
/// A reference to an imported name is never an edge: it never canonicalizes to
/// `VarTopLevel` in the first place (see [`collect_top_level_refs`]), and a cross-module
/// cycle is [`dependencies::ModuleWalker`](super::dependencies::ModuleWalker)'s to report.
/// A body that mentions `v` twice gives one edge.
///
/// Shared by [`check_self_dependency`], which asks which strongly-connected components hold
/// a parameterless binding and a cycle, and [`initialisation_order`] (`GEN-7`), which
/// orders the components — one edge set read by two passes, rather than two graphs built
/// from the same rule.
///
/// Nodes are added in name-sorted order, not `values`' raw `HashMap` iteration order, so
/// node indices — and everything `petgraph` derives from them, such as the order
/// `tarjan_scc` returns components in — depend on the names in the source rather than on
/// `values`' hash seed.
fn dependency_graph(values: &HashMap<Name, Value>) -> DiGraph<(&Name, &Value), ()> {
    let mut graph: DiGraph<(&Name, &Value), ()> = DiGraph::new();
    let mut nodes: HashMap<&Name, NodeIndex> = HashMap::new();

    let mut sorted: Vec<(&Name, &Value)> = values.iter().collect();
    sorted.sort_by(|(l, _), (r, _)| l.as_str().cmp(r.as_str()));

    for &(name, value) in &sorted {
        let idx = graph.add_node((name, value));
        nodes.insert(name, idx);
    }

    for &(name, value) in &sorted {
        let Some(&from) = nodes.get(name) else {
            continue;
        };

        let body = match value {
            Value::Value { body, .. } | Value::TypedValue { body, .. } => body,
        };

        let mut refs = Vec::new();
        collect_top_level_refs(body, &mut refs);

        for referenced in &refs {
            if let Some(&to) = nodes.get(referenced) {
                graph.update_edge(from, to, ());
            }
        }
    }

    graph
}

/// `LANG-35`: a strict, parameterless binding is evaluated once, before the program runs,
/// after everything it depends on — so a binding that depends on itself describes no such
/// order, whether the cycle is one binding long (`x = x`) or runs through other bindings
/// and functions (`a = f 1` beside `f x = a`).
///
/// Reports one [`Error::SelfDependency`] per strongly-connected component of
/// [`dependency_graph`] that both holds a parameterless binding and is a cycle: two or
/// more members, or one member with an edge to itself. `tarjan_scc` puts a single node in
/// its own component whether or not it has that edge, which is why the one-member case is
/// asked separately. A component of functions only is never reported — a function's value
/// exists before its body runs — so `isEven`/`isOdd` and `f n = f n` pass. A binding with
/// an edge to itself inside a larger component (`a = (a, b)` beside `b = a`) is reported
/// once, with that component.
///
/// Members are ordered parameterless bindings first, then functions, each group by name,
/// so the report does not depend on traversal order and its first member — the one the
/// message and the primary label are about — is always a parameterless binding.
fn check_self_dependency(values: &HashMap<Name, Value>) -> Result<(), Vec<Error>> {
    let graph = dependency_graph(values);

    let mut errors = Vec::new();

    for component in petgraph::algo::tarjan_scc(&graph) {
        let cyclic = match component.as_slice() {
            [only] => graph.contains_edge(*only, *only),
            _ => true,
        };
        let holds_binding = component.iter().any(|&idx| is_parameterless(graph[idx].1));

        if !(cyclic && holds_binding) {
            continue;
        }

        let mut members: Vec<CycleMember> = component
            .iter()
            .map(|&idx| {
                let (name, value) = graph[idx];
                CycleMember {
                    name: name.clone(),
                    span: value.span(),
                    function: !is_parameterless(value),
                }
            })
            .collect();
        members.sort_by(|l, r| {
            l.function
                .cmp(&r.function)
                .then_with(|| l.name.as_str().cmp(r.name.as_str()))
        });

        errors.push(Error::SelfDependency(members));
    }

    if errors.is_empty() {
        Ok(())
    } else {
        Err(errors)
    }
}

/// `GEN-7`: the order `module`'s parameterless bindings must be initialised in — each
/// only after every parameterless binding it depends on, through functions as well as
/// directly
/// (`docs/spec/evaluation-semantics.md#a-binding-with-no-parameters-is-evaluated-once`).
///
/// Reads [`dependency_graph`], the graph [`check_self_dependency`] (`LANG-35`) reads, and
/// orders its strongly-connected components dependency-first, keeping only the
/// parameterless bindings. A plain topological sort of the graph itself would not do: a
/// cycle of functions only is legal, and a topological sort refuses any cycle. So the
/// components are condensed to one node each, which is acyclic, and that is what is
/// sorted. Functions take part in the sort — an edge through one is still an edge — but
/// are left out of what comes back.
///
/// Among components with no path between them, the one whose smallest member name sorts
/// first comes first, so the order is fixed by the names in the source: two runs of the
/// compiler over one unchanged module produce the same order, and two independent
/// constants come back in name order.
///
/// After `check_self_dependency` accepts a module, every component holding a
/// parameterless binding is that binding alone, so each binding has one well-defined
/// place. `ir::build`, this function's sole caller, also builds a module canonicalization
/// reported errors for, and one of those can be the cycle `check_self_dependency`
/// rejected. A component holding several parameterless bindings does not panic — this
/// codebase holds `panic!`/`unwrap()`/`expect()` off every non-test path — its bindings
/// come back together, in name order. A module with an error is never emitted, so that
/// order is never run.
///
/// A `module foreign` facade has no parameterless declarations to order for this purpose:
/// `unsafe pi : Float` names a foreign binding directly, with no Zelkova body to place,
/// and is evaluated on whatever schedule the target gives it
/// (`docs/spec/interop.md#facade-constants`), so this returns the empty list for one
/// without inspecting its (structurally parameterless, but synthetic) values.
pub(crate) fn initialisation_order(module: &Module) -> Vec<Name> {
    if module.binding_foreign {
        return Vec::new();
    }

    // `make_acyclic` drops the edges inside a component, so the condensation is a DAG.
    let condensed = petgraph::algo::condensation(dependency_graph(&module.values), true);

    let first_name = |idx: NodeIndex| -> &str {
        condensed[idx]
            .iter()
            .map(|(name, _)| name.as_str())
            .min()
            .unwrap_or_default()
    };

    // An edge `u -> v` means `u` depends on `v`, so a component is ready once every edge
    // out of it has been satisfied. `condensation(g, true)` calls `update_edge` for every
    // original edge between two distinct components, which updates an existing
    // component-to-component edge's weight rather than duplicating it, so no parallel
    // edges between distinct components ever reach `condensed` — the count below and the
    // one edge released per neighbor in the loop are counting the same, already
    // deduplicated set.
    let mut unsatisfied: Vec<usize> = condensed
        .node_indices()
        .map(|idx| condensed.edges_directed(idx, Direction::Outgoing).count())
        .collect();

    let mut ready: BinaryHeap<Reverse<(&str, NodeIndex)>> = condensed
        .node_indices()
        .filter(|idx| unsatisfied[idx.index()] == 0)
        .map(|idx| Reverse((first_name(idx), idx)))
        .collect();

    let mut order = Vec::new();

    while let Some(Reverse((_, idx))) = ready.pop() {
        let mut bindings: Vec<&Name> = condensed[idx]
            .iter()
            .filter(|(_, value)| is_parameterless(value))
            .map(|(name, _)| *name)
            .collect();
        bindings.sort_by(|l, r| l.as_str().cmp(r.as_str()));
        order.extend(bindings.into_iter().cloned());

        for dependent in condensed.neighbors_directed(idx, Direction::Incoming) {
            let count = &mut unsatisfied[dependent.index()];
            *count = count.saturating_sub(1);
            if *count == 0 {
                ready.push(Reverse((first_name(dependent), dependent)));
            }
        }
    }

    order
}

/// What [`do_values`] made of a module's value declarations.
struct Values {
    /// Every declaration that canonicalized.
    values: HashMap<Name, Value>,
    /// Every declaration that did not, in declaration order.
    broken: Vec<Broken>,
    /// Why each of [`broken`](Self::broken) did not, one or two errors per declaration,
    /// and every name a declaration of either list could not resolve, in declaration
    /// order.
    errors: Vec<Error>,
}

/// Canonicalize every value declaration of a module that is not a facade.
///
/// A declaration's annotation is canonicalized first and on its own, so that an error
/// in the body cannot keep the annotation from being read. A declaration whose
/// annotation (when it has one) and body both canonicalize is a [`Value`]. One whose
/// annotation or body does not is [`Broken`], carrying its annotation when that
/// canonicalized, and every error of the two is reported: the annotation's, then the
/// body's. A declaration `unparsed` names — a chunk of it failed to parse — is
/// [`Broken`] whatever its body, with its annotation's error alone reported.
///
/// A name in the body that does not resolve does not stop the body canonicalizing: it
/// is a hole ([`ExpressionKind::Hole`], [`PatternKind::Hole`]), and its error is
/// reported after the declaration's others, whether the declaration is a [`Value`] or
/// [`Broken`].
fn do_values(
    env: &mut RootEnvironment,
    functions: &[parser::Function],
    unparsed: &HashMap<Name, NodeSpan>,
) -> Values {
    // Before resolving expressions, we store the top-level values in the environment.
    // We do so first because their expression below could refer to them.
    for f in functions.iter() {
        env.insert_top_level_value(f.name.clone());
    }

    let mut values = HashMap::new();
    let mut broken = Vec::new();
    let mut errors = Vec::new();

    for function in functions {
        let mut unresolved = Vec::new();
        match value_declaration(env, function, unparsed, &mut unresolved) {
            Ok(value) => {
                values.insert(function.name.clone(), value);
            }
            Err(rejected) => {
                broken.push(rejected.broken);
                errors.extend(rejected.errors);
            }
        }
        errors.extend(unresolved);
    }

    Values {
        values,
        broken,
        errors,
    }
}

/// One value declaration of [`do_values`], or the declaration recorded as broken beside
/// the errors that say why. Every name its body could not resolve is pushed onto
/// `unresolved`, whichever it is.
fn value_declaration(
    env: &RootEnvironment,
    function: &parser::Function,
    unparsed: &HashMap<Name, NodeSpan>,
    unresolved: &mut Vec<Error>,
) -> Result<Value, Box<Rejected>> {
    let annotation = annotation(env, function);

    // A declaration a failed chunk names is broken whatever parsed of it. Its body
    // is not read: a binding that parsed may be one of several, and a missing one
    // may be the chunk that failed, so nothing said about it would be news.
    if let Some(chunk) = unparsed.get(&function.name) {
        return Err(match annotation {
            Annotation::Absent => Rejected::unparsed(function, None, vec![], *chunk),
            Annotation::Canonical(tpe, context) => {
                Rejected::unparsed(function, Some((tpe, context)), vec![], *chunk)
            }
            Annotation::Failed(errors) => Rejected::unparsed(function, None, errors, *chunk),
        });
    }

    match (annotation, value_body(env, function, unresolved)) {
        (Annotation::Absent, Ok((patterns, body))) => Ok(Value::Value {
            name: function.name.clone(),
            patterns,
            body,
            span: function.span,
        }),
        (Annotation::Canonical(tpe, context), Ok((patterns, body))) => {
            let linear = Type::to_linear_types(&tpe);

            // Linear is a list of types making the function. Because it includes the return type,
            // it will always be bigger than the number of patterns by one.
            if !patterns.is_empty() && (linear.len() - 1 != patterns.len()) {
                // TODO Better error message
                debug!(
                    "linear = {:#?}\nbindings = {:#?} (linear.len ({}) != patterns.len ({}))",
                    linear,
                    function.bindings,
                    linear.len(),
                    patterns.len()
                );
                return Err(Rejected::new(
                    function,
                    Some((tpe, context)),
                    vec![Error::BindingPatternsInvalidLen(function.span)],
                ));
            }

            let patterns = patterns.into_iter().zip(linear).collect();

            Ok(Value::TypedValue {
                name: function.name.clone(),
                patterns,
                body,
                tpe,
                context,
                // `do_values` only runs for a module that is not a facade,
                // and `canonicalize` has already rejected a marked
                // annotation there.
                marked_unsafe: false,
                span: function.span,
                annotation_span: function.annotation_span,
            })
        }
        (Annotation::Absent, Err(body_error)) => {
            Err(Rejected::new(function, None, vec![body_error]))
        }
        (Annotation::Canonical(tpe, context), Err(body_error)) => Err(Rejected::new(
            function,
            Some((tpe, context)),
            vec![body_error],
        )),
        (Annotation::Failed(mut errors), body) => {
            errors.extend(body.err());
            Err(Rejected::new(function, None, errors))
        }
    }
}

/// A value declaration recorded as broken, beside the errors that say why.
///
/// Boxed where it is the `Err` of a declaration's result, since a [`Broken`] carries a
/// whole [`Type`] and the `Ok` side is usually the one taken.
struct Rejected {
    broken: Broken,
    errors: Vec<Error>,
}

impl Rejected {
    /// `function`, recorded as broken with `annotation` as its annotation's type and
    /// context, because of `errors`.
    fn new(
        function: &parser::Function,
        annotation: Option<(Type, Vec<Constraint>)>,
        errors: Vec<Error>,
    ) -> Box<Rejected> {
        Box::new(Rejected {
            broken: Broken::of(function, annotation),
            errors,
        })
    }

    /// `function`, which a declaration chunk that failed to parse also declares, recorded
    /// as broken with `annotation` as its annotation's type and context, because of
    /// `errors` and of the syntax error already reported. Its span covers the failed
    /// chunk, `chunk`, as well as what parsed.
    fn unparsed(
        function: &parser::Function,
        annotation: Option<(Type, Vec<Constraint>)>,
        errors: Vec<Error>,
        chunk: NodeSpan,
    ) -> Box<Rejected> {
        let mut rejected = Rejected::new(function, annotation, errors);
        rejected.broken.span = rejected.broken.span.merge(chunk);
        rejected
    }

    /// Every declaration of `rejected`, and every error behind them, in the same order.
    fn split(rejected: impl IntoIterator<Item = Box<Rejected>>) -> (Vec<Broken>, Vec<Error>) {
        let mut broken = Vec::new();
        let mut errors = Vec::new();
        for rejected in rejected {
            broken.push(rejected.broken);
            errors.extend(rejected.errors);
        }
        (broken, errors)
    }
}

/// What a value declaration's annotation canonicalized to, read apart from its body.
enum Annotation {
    /// The declaration has no annotation.
    Absent,
    /// The annotation's type, and the constraints of its context, each resolved.
    Canonical(Type, Vec<Constraint>),
    /// Every error in the annotation: its context's, in the order written, then its
    /// type's.
    Failed(Vec<Error>),
}

/// What `function`'s annotation canonicalizes to, read apart from its body.
///
/// Its context is resolved through the routine a class head's and an instance's go
/// through ([`classes::constraints`]), each constraint held to a variable the type after
/// `=>` mentions. An annotation with a bad constraint fails as one with a bad type does.
fn annotation(env: &RootEnvironment, function: &parser::Function) -> Annotation {
    let Some(written) = &function.tpe else {
        return Annotation::Absent;
    };

    let context = classes::constraints(
        env,
        function.context.as_ref(),
        &classes::written_variables(written),
        Error::ConstraintVariableNotInType,
    );

    match (context, Type::from_parser_type(env, written)) {
        (Ok(context), Ok(tpe)) => Annotation::Canonical(tpe, context),
        (context, tpe) => {
            let mut errors = context.err().unwrap_or_default();
            errors.extend(tpe.err());
            Annotation::Failed(errors)
        }
    }
}

/// The parameters and the body of `function`, a value declaration of a module that is
/// not a facade, or the first error that kept them from canonicalizing. Every name they
/// could not resolve is a hole, with its error pushed onto `unresolved`.
fn value_body(
    env: &RootEnvironment,
    function: &parser::Function,
    unresolved: &mut Vec<Error>,
) -> Result<(Vec<Pattern>, Expression), Error> {
    // TODO Better error message with position of mismatch
    let bindings_size = function
        .bindings
        .iter()
        .all(|v| v.patterns.len() == function.bindings[0].patterns.len());

    if !bindings_size {
        return Err(Error::BindingPatternsInvalidLen(function.span));
    }

    match function.bindings.len() {
        0 => Err(Error::NoBindings(function.span)),
        // if one binding, we can convert directly to canonical format
        1 => match_body(env, &function.bindings[0], unresolved),
        _ => {
            // if multiple bindings, we need to create synthetics variables and put all bindings into a case expression
            Err(Error::MultipleBindingsUnsupported(
                function.name.clone(),
                function.span,
            ))
        }
    }
}

/// The parameters and the body of one binding, its parameters in scope in its body, or
/// the first error that kept them from canonicalizing. Every name they could not resolve
/// is a hole, with its error pushed onto `unresolved`.
fn match_body(
    env: &RootEnvironment,
    binding: &parser::Match,
    unresolved: &mut Vec<Error>,
) -> Result<(Vec<Pattern>, Expression), Error> {
    let mut scoped = env.new_scope();

    let patterns: Vec<Pattern> = binding
        .patterns
        .iter()
        .map(|p| Pattern::from_parser(p, env, unresolved))
        .collect::<Result<Vec<_>, Error>>()?;

    for p in &patterns {
        scoped.expose_pattern(p);
    }

    // Maybe create a case_branch function and make it common with Expression::Case ?
    // Or maybe not at the case_branch level, as here we can have multiple patterns
    // whereas cases cannot.
    // eg. a: Int -> Int -> Int  ==>  a b c = b + c
    let body = Expression::from_parser(&binding.body, &scoped, unresolved)?;

    Ok((patterns, body))
}

/// One binding written inside a class or an instance body, canonicalized as an ordinary
/// value with no annotation.
fn binding_value(
    env: &RootEnvironment,
    binding: &parser::FunBinding,
    unresolved: &mut Vec<Error>,
) -> Result<Value, Error> {
    let (patterns, body) = match_body(env, &binding.pattern, unresolved)?;

    Ok(Value::Value {
        name: binding.name.clone(),
        patterns,
        body,
        span: binding.span,
    })
}

/// Every class member whose name another value of the module already has: a top-level
/// declaration, one a chunk that failed to parse names, or a member of an earlier class.
/// `members` is every member of every class the module writes, with its class and its
/// signature's span, in source order.
fn member_clashes(
    members: &[(&Name, &Name, NodeSpan)],
    functions: &[parser::Function],
    unparsed: &HashMap<Name, NodeSpan>,
) -> Vec<Error> {
    let mut errors = Vec::new();

    for (index, (member, class, span)) in members.iter().enumerate() {
        let value = functions
            .iter()
            .find(|f| &f.name == *member)
            .map(|f| f.span)
            .or_else(|| unparsed.get(*member).copied());

        if let Some(other) = value {
            errors.push(Error::MemberNameTaken(
                (*member).clone(),
                (*class).clone(),
                None,
                *span,
                other,
            ));
            continue;
        }

        // A member repeated inside one class is that class's own error.
        if let Some((_, other_class, other)) = members[..index]
            .iter()
            .find(|(earlier, earlier_class, _)| earlier == member && earlier_class != class)
        {
            errors.push(Error::MemberNameTaken(
                (*member).clone(),
                (*class).clone(),
                Some((*other_class).clone()),
                *span,
                *other,
            ));
        }
    }

    errors
}

/// Canonicalize every `type` declaration of a module, keeping each one that canonicalized
/// beside the errors of those that did not.
fn do_types(
    env: &dyn Environment,
    types: &[parser::UnionType],
) -> (HashMap<Name, UnionType>, Vec<Error>) {
    let iter = types.iter().map(|tpe| {
        let tpe_name = tpe.name.clone();
        // The declaration is this module's, so this is where its variants learn
        // which module the type they build belongs to (`AST-4`).
        let qualified_tpe_name = env.module_name().qualify_name(&tpe_name);
        let variables = tpe.type_arguments.clone();

        trace!("do_types(in:{:?})", tpe);

        // An opaque scalar's declaration writes only its own name and contributes
        // no constructor (`LANG-59`, `DEC-15` decision 2): nothing in the language
        // builds or inspects an `Int`, a `Float`, a `Char` or a `String`, so the
        // only body worth accepting is the one that says so. This runs on the
        // *qualified* name, the same way `scalars::Scalar::declares` always does —
        // a module other than the one a scalar is declared in shares its spelling
        // and nothing else (`BUG-26`), so its own `type Int = …` reaches the
        // ordinary path below untouched.
        if let Some(scalar) = scalars::opaque_scalar_of(&qualified_tpe_name) {
            let is_self_naming = matches!(
                tpe.variants.as_slice(),
                [variant] if matches!(
                    &variant.kind,
                    parser::TypeKind::Unqualified(name, args) if *name == tpe_name && args.is_empty()
                )
            );

            if !is_self_naming {
                return Err(Error::InvalidScalarDeclaration(
                    scalar.qual_name(),
                    tpe.span,
                ));
            }

            return Ok((
                tpe_name,
                UnionType {
                    variables,
                    variants: Vec::new(),
                    span: tpe.span,
                },
            ));
        }

        // A variant is a constructor name and its arguments, which the parser spells
        // `TypeKind::Unqualified`. It is the grammar's general `Type` production that
        // parses a variant list, though, so the five other kinds arrive here too —
        // and each is a declaration the user wrote that has no meaning, not a variant
        // this pass may leave out. Skipping one deletes a constructor from the
        // declaration and reports nothing, which was `BUG-18`.
        //
        // The `collect` below short-circuits on the first `Err`, so only the first bad
        // variant in a single `type` declaration is reported — `type T = c | (Int,
        // Int)` names only `c`. The enclosing `collect_partial` still reports the
        // next `type` declaration independently, matching what the `Unqualified` arm
        // already did for `from_parser_type`.
        let variants = tpe
            .variants
            .iter()
            .map(|t| match &t.kind {
                // TODO It might actually make more sense to put Type::from_parser_type
                // on `Environment`.
                parser::TypeKind::Unqualified(name, vars) => {
                    let type_parameters = vars
                        .iter()
                        .map(|t| Type::from_parser_type(env, t))
                        .collect::<Result<Vec<_>, Error>>()?;

                    Ok(TypeConstructor {
                        name: name.clone(),
                        type_parameters,
                        tpe: qualified_tpe_name.clone(),
                    })
                }
                parser::TypeKind::Variable(name) => Err(Error::InvalidVariant(
                    InvalidVariantKind::LowercaseName(name.clone()),
                    t.span,
                )),
                parser::TypeKind::Tuple(_) => {
                    Err(Error::InvalidVariant(InvalidVariantKind::Tuple, t.span))
                }
                parser::TypeKind::Unit => {
                    Err(Error::InvalidVariant(InvalidVariantKind::Unit, t.span))
                }
                parser::TypeKind::Arrow(_, _) => {
                    Err(Error::InvalidVariant(InvalidVariantKind::Arrow, t.span))
                }
                parser::TypeKind::Record(_) => {
                    Err(Error::InvalidVariant(InvalidVariantKind::Record, t.span))
                }
            })
            .collect::<Result<Vec<_>, Error>>()?;

        Ok((
            tpe_name,
            UnionType {
                variables,
                variants,
                span: tpe.span,
            },
        ))
    });

    collect_partial(iter)
}

/// Canonicalize every `infix` declaration of a module, registering each one that names a
/// function this module declares, beside the errors of those that do not. A function
/// `unparsed` names is declared, though nothing of it parsed, and so is a member of one of
/// the module's classes, `members`.
fn do_infixes(
    infixes: &[parser::Infix],
    env: &mut RootEnvironment,
    functions: &[parser::Function],
    members: &[(&Name, &Name, NodeSpan)],
    unparsed: &HashMap<Name, NodeSpan>,
) -> (HashMap<Name, Infix>, Vec<Error>) {
    let iter = infixes.iter().map(|infix| {
        let op_name = infix.operator.clone();
        let function_name = infix.function_name.clone();

        let function_exist = functions.iter().any(|f| f.name == infix.function_name)
            || unparsed.contains_key(&infix.function_name)
            || members
                .iter()
                .any(|(member, _, _)| **member == infix.function_name);

        if function_exist {
            let infix = Infix {
                associativity: infix.associativity,
                precedence: infix.precedence,
                function_name,
                span: infix.span,
            };

            env.insert_local_infix(op_name.clone(), infix.clone());

            Ok((op_name, infix))
        } else {
            Err(Error::InfixReferenceInvalidValue(
                op_name,
                function_name,
                infix.span,
            ))
        }
    });

    collect_partial(iter)
}

// The `Lower` and `Upper` arms below check that the name they name is one this module
// declares: such a name in a module's own `exposing (...)` header that nothing declares, or
// that only an import brought into scope, is `Error::ExportNotFound`
// (`docs/spec/modules.md#everything-exposed-must-be-declared-here`). The `Operator` arm
// checks only that an `infix` of that name is in scope (`local_infix_exists`, which asks
// whether the environment's `infixes` map has the key, and an import fills that map), so an
// operator only an import brought in is accepted; `BUG-51` is the ticket. `Upper`'s two arms
// differ only in which `ExportType` they report on success: `Privacy` governs whether the
// type's constructors are exposed, not whether the type itself exists, so both check
// existence the same way.
//
// What tells a declaration from an import differs by kind, each by what the environment
// already records. A value is `ValueType::Local`/`TopLevel` when this module declares it
// and `Foreign`/`Foreigns` when an import brought it in. A type and a class carry the
// qualified name of their declaration, and `declaring_module` of it is this module only
// for a declaration of its own (`declares_type`, `classes::declaring_module`).
//
// A declaration and an unqualified import of one name do not reach this check as two
// candidates: the declaration replaces the import's entry in `env` before any export is
// read, so such a name counts as declared here. That collision is an error of its own
// (`docs/spec/name-resolution.md#a-top-level-name-comes-from-exactly-one-place`), not
// something this function decides.
//
// `values` is this module's own declarations (from `do_values`/the facade iterator above),
// separate from `env`: `env.find_value` also answers `Some` for a name resolved through an
// import. A name reaches `Lower`'s annotation check only once the arm has established it is
// `TopLevel`/`Local`, so that check never has to consider an imported name.
//
// `unannotated_broken` is the declarations of this module that were written with no
// annotation and are in `Module::broken` — absent from `values`, so without it an exposed
// one would be accepted here and then be missing from the interface with nothing in this
// module to say why. Each is reported exactly as an unannotated `Value::Value` is.
//
// What comes back is the exports that resolved beside the errors of those that did not:
// for an explicit list, every entry that did not error, so a bad entry costs the module
// that entry alone; for `exposing (..)`, everything, beside an error per unannotated
// declaration.
//
// `member_classes` is each member of this module's own classes, to its class. A member is
// exposed with its class, and an entry naming one alone is an error.
fn do_exports(
    source_exposing: &parser::Exposing,
    env: &RootEnvironment,
    values: &HashMap<Name, Value>,
    unannotated_broken: &HashMap<Name, NodeSpan>,
    member_classes: &HashMap<&Name, &Name>,
) -> (Exports, Vec<Error>) {
    match source_exposing {
        // `exposing (..)` exposes every top-level declaration this module
        // makes, so `SPEC-5` applies to every one of them, not just those
        // named individually — and there is no per-name span in this header
        // to blame (`parser::Exposing::Open` carries none), so
        // `ExportedValueNotAnnotated`'s first span is `NodeSpan::none()` and
        // the declaration itself is what a diagnostic points at.
        parser::Exposing::Open => {
            let checked = values.values().map(|value| match value {
                Value::TypedValue { .. } => Ok(()),
                Value::Value { name, span, .. } => Err(Error::ExportedValueNotAnnotated(
                    name.clone(),
                    NodeSpan::none(),
                    *span,
                )),
            });

            let ((), mut errors) = collect_partial(checked);
            errors.extend(unannotated_broken.iter().map(|(name, span)| {
                Error::ExportedValueNotAnnotated(name.clone(), NodeSpan::none(), *span)
            }));

            (Exports::Everything, errors)
        }
        parser::Exposing::Explicit(exposed) => {
            let specifics =
                exposed.iter().map(|exposed| match &exposed.kind {
                    parser::ExposedKind::Lower(name) => {
                        if let Some(class) = member_classes.get(name) {
                            return Err(Error::MemberExposedAlone(
                                name.clone(),
                                (*class).clone(),
                                exposed.span,
                            ));
                        }

                        // Only a declaration of this module is exposed by it: a name an
                        // `import ... exposing (...)` brought in is `Foreign`/`Foreigns`,
                        // and is as much `ExportNotFound` as one nothing declares.
                        if !matches!(
                            env.find_value(name),
                            Some(ValueType::Local | ValueType::TopLevel)
                        ) {
                            return Err(Error::ExportNotFound(
                                name.clone(),
                                ExportType::Value,
                                exposed.span,
                            ));
                        }

                        if let Some(span) = unannotated_broken.get(name) {
                            return Err(Error::ExportedValueNotAnnotated(
                                name.clone(),
                                exposed.span,
                                *span,
                            ));
                        }

                        match values.get(name) {
                            Some(Value::Value { span, .. }) => Err(
                                Error::ExportedValueNotAnnotated(name.clone(), exposed.span, *span),
                            ),
                            // `Some(TypedValue)` is declared locally and annotated;
                            // `None` is a local declaration that is not in `values`
                            // (one whose annotation was rejected, say), whose own error
                            // is already reported.
                            Some(Value::TypedValue { .. }) | None => {
                                Ok((name.clone(), ExportType::Value))
                            }
                        }
                    }
                    // Privacy governs whether the type's constructors are exposed,
                    // not whether the type itself exists — both arms check
                    // existence the same way, and only the `ExportType` they
                    // report on success differs.
                    parser::ExposedKind::Upper(name, parser::Privacy::Public) => {
                        if declares_type(env, name) {
                            Ok((name.clone(), ExportType::UnionPublic))
                        } else if env.find_class(name).is_some() {
                            Err(Error::ClassExposedWithConstructors(
                                name.clone(),
                                exposed.span,
                            ))
                        } else {
                            Err(Error::ExportNotFound(
                                name.clone(),
                                ExportType::UnionPublic,
                                exposed.span,
                            ))
                        }
                    }
                    parser::ExposedKind::Upper(name, parser::Privacy::Private) => {
                        if declares_type(env, name) {
                            Ok((name.clone(), ExportType::UnionPrivate))
                        } else if let Some(class) = env.find_class(name) {
                            // A class an import brought into scope is one this module
                            // may not re-export
                            // (docs/spec/modules.md#everything-exposed-must-be-declared-here).
                            if classes::declaring_module(class) == *env.module_name() {
                                Ok((name.clone(), ExportType::Class))
                            } else {
                                Err(Error::ExportNotFound(
                                    name.clone(),
                                    ExportType::Class,
                                    exposed.span,
                                ))
                            }
                        } else {
                            Err(Error::ExportNotFound(
                                name.clone(),
                                ExportType::UnionPrivate,
                                exposed.span,
                            ))
                        }
                    }
                    parser::ExposedKind::Operator(name) => {
                        if env.local_infix_exists(name) {
                            Ok((name.clone(), ExportType::Infix))
                        } else {
                            Err(Error::ExportNotFound(
                                name.clone(),
                                ExportType::Infix,
                                exposed.span,
                            ))
                        }
                    }
                });

            let (specifics, errors) = collect_partial(specifics);

            (Exports::Specifics(specifics), errors)
        }
    }
}

/// Whether `name` is a type this module declares, as opposed to one an import brought
/// into scope under that spelling: the [`TypeArity`](environment::TypeArity) a lookup
/// finds records the declaration's qualified name, so it is this module's when the module
/// that name carries is this one.
fn declares_type(env: &RootEnvironment, name: &Name) -> bool {
    env.find_type(name)
        .is_some_and(|declared| classes::declaring_module(&declared.name) == *env.module_name())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn not_found() -> Error {
        Error::TypeNotFound("T".into(), NodeSpan::none())
    }

    fn no_bindings() -> Error {
        Error::NoBindings(NodeSpan::none())
    }

    /// A group is flattened before the filter reads it, so a member that is not a
    /// restatement survives its group, and a group holding only restatements leaves
    /// nothing behind. With the flag unset the list comes back as it went in, groups
    /// included.
    ///
    /// Mutation-checked by pushing a group through without flattening it: the group is
    /// kept whole and the first assertion goes red.
    #[test]
    fn without_restated_flattens_groups_and_keeps_what_is_not_a_missing_name() {
        let errors = vec![
            Error::Many(vec![
                Error::Many(vec![not_found(), no_bindings()]),
                not_found(),
            ]),
            Error::Many(vec![not_found()]),
        ];

        let kept = without_restated(errors, true);
        assert!(
            matches!(kept.as_slice(), [Error::NoBindings(_)]),
            "got {:?}",
            kept
        );

        let untouched = without_restated(vec![Error::Many(vec![not_found()])], false);
        assert!(
            matches!(untouched.as_slice(), [Error::Many(members)] if members.len() == 1),
            "got {:?}",
            untouched
        );
    }
}