beck_core/

iface.rs

//! `.becki` — the published module signature, and the separate-compilation firewall.
//!
//! [`docs/03-type-and-effect-system.md`](../../../../../docs/03-type-and-effect-system.md) §3.6, whose
//! heading is "Modularity and separate compilation (**do not defer**)", and whose rule is one
//! sentence:
//!
//! > **Placement, effects, and event/command types are part of a module's published signature.**
//! > Inference is intra-module; boundaries are declared.
//!
//! [`docs/01-vision-and-premise.md`](../../../../../docs/01-vision-and-premise.md) §1.6 says why this
//! is the item that cannot slip: it is the historical killer of tierless languages. A language that
//! must see every module to place any of them has a build time proportional to the whole program
//! and an API surface nobody can review.
//!
//! # What a `.becki` is
//!
//! A **file in the ordinary Beck surface**, generated by `beck iface`, checked in, and reviewed like
//! an `.mli`. It contains the module's types verbatim and one bodyless `def` per published name:
//!
//! ```text
//! # orders.becki — generated by `beck iface`. This is the module's published contract.
//!
//! model Order:
//!     id: OrderId
//!     total: Int
//!
//! @on(any)
//! def recent(customer: Str, limit: Int) -> list[Order]
//!
//! @signal
//! @on(data)
//! def orders() -> Signal[Map[OrderId, Order]] uses durable
//! ```
//!
//! Two decisions worth stating, because §3.6's illustrative syntax suggests otherwise:
//!
//! * **It is Beck, not a second notation.** §3.6 sketches `orders : Signal[…] ! { durable }
//!   @on(server)`, which would need a parser of its own. A bodyless `def` says the same thing in a
//!   grammar the lexer, parser, printer, formatter and editor already handle, and `beck fmt` keeps
//!   it tidy for free. The one parser change it needed — a `def` may have no body — is a
//!   declaration, which is a thing the language wanted anyway (a trait's method signature is one).
//! * **A published signal is a nullary declaration**, marked `@signal`. A signal is a *value* of
//!   type `Signal[T]`, and declaring a value with no arguments is what an interface file has always
//!   done; the marker distinguishes it from a function that happens to return one.
//!
//! # Why the digest matters
//!
//! [`Interface::digest`] is the firewall in one value. A body edit does not change it, so a
//! downstream module's check is served from the memo; an effect or a type or a placement change
//! does change it, so the downstream module is re-checked — and, if the change is breaking,
//! `beck check --wire-compat` says so before the deploy does.

use std::collections::BTreeMap;
use std::fmt::Write as _;
use std::sync::Arc;

use beck_diag::{Diagnostic, Diagnostics, SourceMap};

use crate::check::Program;
use crate::ty::{self, Effect, ImplSig, Row, Scheme, Tier, TraitSig, Ty, TyDecl};

/// One published name.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Item {
    pub name: Arc<str>,
    /// The trait bounds on this name's type parameters. A bounded definition publishes the bound
    /// and *not* the dictionary parameters it was lowered with: those are named
    /// `Trait::method@T` and belong to the lowering rather than to the contract, and an importing
    /// module reconstructs them from the bound.
    pub bounds: Vec<(Arc<str>, Vec<Arc<str>>)>,
    pub kind: Kind,
    /// The effect row, as atoms. A published row is always closed: §3.6 says boundaries are
    /// declared, and a row variable is an inference artefact that has no meaning outside the module
    /// that solved it.
    pub effects: Vec<Effect>,
    pub tier: Tier,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Kind {
    Function {
        /// The names a generic definition quantifies over, in the order written. Empty for the
        /// monomorphic case, which is every definition written before `docs/27`.
        typarams: Vec<Arc<str>>,
        params: Vec<(Arc<str>, Ty)>,
        ret: Ty,
    },
    Signal {
        ty: Ty,
    },
}

/// A module's published signature.
#[derive(Clone, Debug, PartialEq, Eq, Default)]
pub struct Interface {
    pub module: String,
    /// The modules this contract was checked against, rendered as `import` lines.
    ///
    /// A `.becki` is read back **as a module**, so a name it uses but does not declare has to be
    /// resolvable from the file itself. A published `impl Priced for Book`, or a bound
    /// `def total[T: Priced]`, names a trait that may live in another module — and without the
    /// import line the reader has nothing to resolve `Priced` against and reports `B0383`, which
    /// made `beck iface` write a file `beck check` refused.
    ///
    /// Deliberately **not** in [`Interface::digest`]: the digest is about the signatures published,
    /// and this is provenance for resolving the names in them. Hashing it would report an API
    /// change to every consumer when a module gained an import its contract never mentions.
    pub imports: Vec<String>,
    /// Types in declaration order, so the rendered file is stable.
    pub types: Vec<TyDecl>,
    /// The `trait` declarations this module owns.
    pub traits: Vec<TraitSig>,
    /// The `impl` headers this module owns — the bodies stay behind, and what crosses is that the
    /// implementation exists and what it promises. Without these, a call in an importing module has
    /// a trait and nothing to resolve it to.
    pub impls: Vec<ImplSig>,
    pub items: Vec<Item>,
}

impl Interface {
    /// Extract the interface of a checked, placed program.
    pub fn of(program: &Program) -> Interface {
        // Only what this module declares. The prelude belongs to the language, and an imported
        // type is published by the module that owns it — republishing one would make two modules
        // claim the same contract.
        // Declaration order, not alphabetical: a type may name one declared before it, and the
        // rendered file has to be a file the checker can read back.
        let types: Vec<TyDecl> = program
            .own_types
            .iter()
            .filter_map(|n| program.types.get(n).cloned())
            .collect();
        let traits = program.traits.clone();
        let impls = program.impls.clone();
        // Every import, rather than the subset the published signatures reach. Nothing records
        // which import a trait name arrived through — the checker's table is flat — and
        // over-approximating costs a reader nothing, while guessing the subset wrong costs them a
        // `B0383` on a file they did not write.
        let imports = program.imports.clone();

        let mut items = Vec::new();
        for name in &program.def_order {
            let Some(d) = program.defs.get(name) else {
                continue;
            };
            // A desugared impl method is not part of the contract: its name is compiler-generated
            // and no parser could read it back. What crosses instead is the `impl` header, which
            // says the implementation exists, and the trait, which says what it promises.
            if crate::check::is_impl_method(name) {
                continue;
            }
            // A bounded definition publishes its written parameters. The dictionaries were appended
            // by the lowering and are recovered by the importer from the same bound.
            let written = d.params.len() - dict_count(d);
            items.push(Item {
                name: d.name.clone(),
                bounds: d.bounds.clone(),
                kind: if d.declares_signal {
                    Kind::Signal {
                        ty: close_rows(&d.ret),
                    }
                } else {
                    Kind::Function {
                        typarams: d.typarams.clone(),
                        params: d.params[..written]
                            .iter()
                            .map(|(_, n, t)| (n.clone(), close_rows(t)))
                            .collect(),
                        ret: close_rows(&d.ret),
                    }
                },
                effects: published(&d.row),
                tier: d.tier,
            });
        }
        for s in &program.signals {
            items.push(Item {
                name: s.name.clone(),
                bounds: Vec::new(),
                kind: Kind::Signal {
                    ty: close_rows(&s.ty),
                },
                effects: published(&s.row),
                tier: s.tier,
            });
        }
        items.sort_by(|a, b| a.name.cmp(&b.name));

        Interface {
            module: program.name.clone(),
            imports,
            types,
            traits,
            impls,
            items,
        }
    }

    pub fn item(&self, name: &str) -> Option<&Item> {
        self.items.iter().find(|i| i.name.as_ref() == name)
    }

    /// A content hash of everything a downstream module can depend on.
    ///
    /// Deliberately *not* a hash of the rendered file: a comment, or a change of field order in the
    /// printer, must not invalidate a build. It is a hash of the meaning.
    pub fn digest(&self) -> String {
        let mut h = blake3::Hasher::new();
        h.update(self.module.as_bytes());
        // Sorted, unlike the rendered order: moving two independent declarations past each other
        // changes the file and not the contract, and the digest is about the contract.
        let mut types: Vec<String> = self.types.iter().map(type_signature).collect();
        types.sort();
        for t in &types {
            h.update(b"T");
            h.update(t.as_bytes());
        }
        for t in &self.traits {
            h.update(b"R");
            h.update(trait_signature(t).as_bytes());
        }
        for i in &self.impls {
            h.update(b"M");
            h.update(impl_signature(i).as_bytes());
        }
        for i in &self.items {
            h.update(b"I");
            h.update(i.name.as_bytes());
            h.update(item_signature(i).as_bytes());
        }
        h.finalize().to_hex()[..32].to_string()
    }

    /// Render the `.becki` file.
    pub fn render(&self) -> String {
        let mut out = String::new();
        let _ = writeln!(
            out,
            "# {}.becki — generated by `beck iface`.\n\
             #\n\
             # This is the module's published contract: its types, and every name's signature with\n\
             # the effects it performs and the tier it runs on. Review it like an .mli — a change\n\
             # here is an API change, and `beck check --wire-compat` will say which kind.\n",
            self.module
        );
        // First, because the file is read back as a module and everything below may name something
        // one of these declares.
        for m in &self.imports {
            let _ = writeln!(out, "import {m}");
        }
        if !self.imports.is_empty() {
            out.push('\n');
        }
        for t in &self.types {
            out.push_str(&render_type(t));
            out.push('\n');
        }
        for t in &self.traits {
            out.push_str(&render_trait(t));
            out.push('\n');
        }
        // After the traits and before the definitions, because an impl names both a trait and a
        // type and the checker reads a file once, in order.
        for i in &self.impls {
            let _ = writeln!(out, "{}", render_impl(i));
        }
        if !self.impls.is_empty() {
            out.push('\n');
        }
        for i in &self.items {
            if let Kind::Signal { .. } = i.kind {
                out.push_str("@signal\n");
            }
            let _ = writeln!(out, "@on({})", i.tier.name());
            out.push_str(&render_item(i));
            out.push('\n');
        }
        out
    }

    /// Read a `.becki` back.
    ///
    /// The **caller's** `SourceMap`, for the same reason [`crate::project`] gives one to every
    /// module it loads: a diagnostic about `orders.becki` has to point into `orders.becki`. A map
    /// made and dropped here would leave every diagnostic carrying a `FileId` the renderer resolves
    /// against somebody else's file, which is worse than no span at all — it points confidently at
    /// an unrelated line.
    pub fn parse(
        module: &str,
        src: &str,
        map: &mut SourceMap,
        diags: &mut Diagnostics,
    ) -> Interface {
        Interface::parse_with(module, src, &[], map, diags)
    }

    /// The same, against the interfaces of the modules this one imports.
    ///
    /// A `.becki` is checked as a module, so a name it uses but does not declare needs the same
    /// thing a `.beck` needs: the contract of whatever declares it. A published `impl Priced for
    /// Book` or a bound `def total[T: Priced]` names a trait that may live elsewhere, and reading
    /// the file with nothing to resolve against reported `B0383` — `beck iface` wrote a file
    /// `beck check` refused. [`crate::project`] has every dependency's interface in hand by the
    /// time it reads this one, because it works in dependency order, deepest first.
    ///
    /// [`Interface::parse`] passing none is still right for a caller that has none — comparing an
    /// old contract to a new one for `--wire-compat` reads signatures, and a trait it cannot
    /// resolve is reported rather than silently accepted.
    pub fn parse_with(
        module: &str,
        src: &str,
        imports: &[(String, Interface)],
        map: &mut SourceMap,
        diags: &mut Diagnostics,
    ) -> Interface {
        let file = map.add(format!("{module}.becki"), src);
        let node = beck_syntax::parse_file(file, module, src, diags);
        // An interface is checked as a module: the same resolver, the same type syntax, the same
        // diagnostics. What makes it an interface is that every `def` in it is bodyless.
        let program =
            crate::check::check_module_with(&node, crate::check::Mode::Interface, imports, diags);
        for name in &program.def_order {
            if let Some(d) = program.defs.get(name) {
                if !d.is_declaration {
                    diags.push(
                        Diagnostic::error(
                            "B0600",
                            format!("`{name}` has a body, so it is not a signature"),
                            d.span,
                        )
                        .with_note(
                            "a `.becki` publishes what a module offers, not how it does it; \
                             regenerate it with `beck iface`",
                        ),
                    );
                }
            }
        }
        let mut iface = Interface::of(&program);
        // Through the same normalisation the parser applies, so a contract read from `orders.becki`
        // and one derived from `orders.beck` agree on what module they describe — otherwise the
        // digest would differ for a reason nobody wrote down.
        iface.module = beck_syntax::module_ident(module);
        // From the **file**, not from what this call was handed. `Interface::of` reads
        // `Program::imports`, which is the list the checker was given, so a contract read with none
        // supplied would re-render without the `import` lines it was written with — a round trip
        // that loses what the reader needs on the next pass.
        iface.imports = node
            .args
            .iter()
            .skip(1)
            .filter(|n| n.is_form(beck_syntax::sym::IMPORT))
            .filter_map(|n| n.args.first().and_then(|a| a.as_var()))
            .map(|s| s.as_str().to_string())
            .collect();
        // `Interface::of` reads placement off the program, and a parsed interface has no solver
        // behind it — the tiers are the ones written in the file, which is what `@on(…)` means.
        iface
    }

    /// Register this interface's types and names in a checker's environment.
    pub fn exports(&self) -> (BTreeMap<Arc<str>, TyDecl>, BTreeMap<Arc<str>, Export>) {
        let types = self
            .types
            .iter()
            .map(|t| (t.name().clone(), t.clone()))
            .collect();
        let names = self
            .items
            .iter()
            .map(|i| {
                let scheme = match &i.kind {
                    // `generic` and not `mono`: an importer has to instantiate a published
                    // `map[T, U]` afresh per call, or the first use would fix the second's types.
                    Kind::Function {
                        typarams,
                        params,
                        ret,
                    } => Scheme::generic(
                        typarams.clone(),
                        Ty::fun_eff(
                            params.iter().map(|(_, t)| t.clone()).collect(),
                            ret.clone(),
                            Row::of(i.effects.iter().cloned()),
                        ),
                    ),
                    Kind::Signal { ty } => Scheme::mono(ty.clone()),
                };
                (
                    i.name.clone(),
                    Export {
                        scheme,
                        bounds: i.bounds.clone(),
                        row: Row::of(i.effects.iter().cloned()),
                        tier: i.tier,
                        is_signal: matches!(i.kind, Kind::Signal { .. }),
                    },
                )
            })
            .collect();
        (types, names)
    }
}

/// What an importing module learns about one imported name.
#[derive(Clone, Debug)]
pub struct Export {
    pub scheme: Scheme,
    /// The bounds the importer has to reconstruct dictionaries from.
    pub bounds: Vec<(Arc<str>, Vec<Arc<str>>)>,
    pub row: Row,
    pub tier: Tier,
    pub is_signal: bool,
}

/// Close every row inside a type.
///
/// A row *variable* is an inference artefact: its number comes from the order the checker happened
/// to mint it in, so two compilations of the same unchanged module would publish different-looking
/// contracts and the firewall would never hold. §3.6 says boundaries are declared, and a variable is
/// not a declaration.
///
/// The cost is named rather than hidden: **effect polymorphism does not cross a module boundary in
/// Phase 2.** An exported higher-order function publishes its function parameter's row as closed, so
/// an importer passing an effectful argument where the contract says pure is refused. That is the
/// sound direction — it rejects a program that could have been accepted, never the reverse — and it
/// is the first thing to revisit if a real library runs into it.
fn close_rows(t: &Ty) -> Ty {
    match t {
        Ty::Var(v) => Ty::Var(*v),
        Ty::Con(n, args) => Ty::Con(n.clone(), args.iter().map(close_rows).collect()),
        Ty::Fun(ps, r, row) => Ty::Fun(
            ps.iter().map(close_rows).collect(),
            Box::new(close_rows(r)),
            Row::of(row.atoms.iter().filter(|e| !e.is_ambient()).cloned()),
        ),
    }
}

/// The row as published: closed, and without the ambient set (§3.2).
fn published(row: &Row) -> Vec<Effect> {
    let mut out = row.visible();
    out.sort();
    out
}

fn item_signature(i: &Item) -> String {
    let bounds: String = i
        .bounds
        .iter()
        .map(|(p, ts)| format!("{p}:{};", ts.join("+")))
        .collect();
    let ty = match &i.kind {
        // The type parameters are part of the signature the digest covers: `map[T, U]` and
        // `map[T]` are different contracts even when the printed parameter list is the same.
        Kind::Function {
            typarams,
            params,
            ret,
        } => format!(
            "{bounds}{}({}) -> {ret}",
            if typarams.is_empty() {
                String::new()
            } else {
                format!("[{}]", typarams.join(", "))
            },
            params
                .iter()
                .map(|(n, t)| format!("{n}: {t}"))
                .collect::<Vec<_>>()
                .join(", ")
        ),
        Kind::Signal { ty } => format!("{ty}"),
    };
    format!(
        "{ty} ! {{{}}} @on({})",
        i.effects
            .iter()
            .map(|e| e.name())
            .collect::<Vec<_>>()
            .join(", "),
        i.tier.name()
    )
}

/// A type's structure, transitively — every field of every variant, through every named type it
/// reaches.
///
/// §4.3 asks for an operation id that is "content-derived … stable across refactors that don't
/// change the signature". A hash of the type's *name* satisfies neither half: it does not move when
/// a field is added, which is the change that breaks every open tab. This is what content means.
pub fn structural(ty: &Ty, types: &BTreeMap<Arc<str>, TyDecl>) -> String {
    fn go(ty: &Ty, types: &BTreeMap<Arc<str>, TyDecl>, seen: &mut Vec<Arc<str>>, out: &mut String) {
        match ty {
            Ty::Var(v) => {
                let _ = write!(out, "?{v}");
            }
            Ty::Fun(ps, r, row) => {
                out.push('(');
                for p in ps {
                    go(p, types, seen, out);
                    out.push(',');
                }
                out.push_str(")->");
                go(r, types, seen, out);
                let _ = write!(out, "!{row}");
            }
            Ty::Con(n, args) => {
                out.push_str(n);
                if !args.is_empty() {
                    out.push('[');
                    for a in args {
                        go(a, types, seen, out);
                        out.push(',');
                    }
                    out.push(']');
                }
                if seen.iter().any(|s| s == n) {
                    return;
                }
                let Some(decl) = types.get(n.as_ref()) else {
                    return;
                };
                seen.push(n.clone());
                out.push('{');
                // Instantiated, so the hash describes the shape this mention actually has:
                // `Envelope[Added]` carries a `body: Added`, and hashing the declaration's
                // `body: ?1000000` instead would make it the same boundary as `Envelope[Toggled]`.
                let at = |t: &Ty| ty::instantiate_decl(t, args);
                match decl {
                    TyDecl::Model { fields, .. } => {
                        for (f, t) in fields {
                            let _ = write!(out, "{f}:");
                            go(&at(t), types, seen, out);
                            out.push(';');
                        }
                    }
                    TyDecl::Union { variants, .. } => {
                        for v in variants {
                            let _ = write!(out, "{}(", v.name);
                            for (f, t) in &v.fields {
                                let _ = write!(out, "{f}:");
                                go(&at(t), types, seen, out);
                                out.push(',');
                            }
                            out.push_str(");");
                        }
                    }
                    TyDecl::Newtype { inner, .. } | TyDecl::Alias { ty: inner, .. } => {
                        go(&at(inner), types, seen, out)
                    }
                }
                out.push('}');
                seen.pop();
            }
        }
    }
    let mut out = String::new();
    go(ty, types, &mut Vec::new(), &mut out);
    out
}

fn fields_as_written(fields: &[(Arc<str>, Ty)], d: &TyDecl) -> String {
    fields
        .iter()
        .map(|(n, t)| format!("{n}: {}", d.as_written(t)))
        .collect::<Vec<_>>()
        .join(", ")
}

fn type_signature(d: &TyDecl) -> String {
    let p = d.param_brackets();
    match d {
        TyDecl::Model { name, fields, .. } => {
            format!("model {name}{p} {{{}}}", fields_as_written(fields, d))
        }
        TyDecl::Union { name, variants, .. } => format!(
            "union {name}{p} {{{}}}",
            variants
                .iter()
                .map(|v| format!("{}({})", v.name, fields_as_written(&v.fields, d)))
                .collect::<Vec<_>>()
                .join(" | ")
        ),
        TyDecl::Newtype { name, inner, .. } => {
            format!("newtype {name}{p} = {}", d.as_written(inner))
        }
        TyDecl::Alias { name, ty, .. } => format!("alias {name}{p} = {}", d.as_written(ty)),
    }
}

fn render_type(d: &TyDecl) -> String {
    let mut out = String::new();
    let p = d.param_brackets();
    match d {
        TyDecl::Model { name, fields, .. } => {
            let _ = writeln!(out, "model {name}{p}:");
            if fields.is_empty() {
                let _ = writeln!(out, "    pass");
            }
            for (n, t) in fields {
                let _ = writeln!(out, "    {n}: {}", d.as_written(t));
            }
        }
        TyDecl::Union { name, variants, .. } => {
            let _ = writeln!(out, "union {name}{p}:");
            for v in variants {
                if v.fields.is_empty() {
                    let _ = writeln!(out, "    {}", v.name);
                } else {
                    let _ = writeln!(out, "    {}({})", v.name, fields_as_written(&v.fields, d));
                }
            }
        }
        TyDecl::Newtype { name, inner, .. } => {
            let _ = writeln!(out, "type {name}{p} = newtype[{}]", d.as_written(inner));
        }
        TyDecl::Alias { name, ty, .. } => {
            let _ = writeln!(out, "type {name}{p} = {}", d.as_written(ty));
        }
    }
    out
}

/// How many of a definition's parameters the bound lowering appended.
///
/// Counted from the names rather than tracked separately, because the names are what makes them
/// recognisable — a dictionary is `Trait::method@T`, and nothing a program writes can be.
fn dict_count(d: &crate::check::Def) -> usize {
    d.params
        .iter()
        .filter(|(_, n, _)| crate::check::is_impl_method(n))
        .count()
}

fn render_trait(t: &TraitSig) -> String {
    let mut out = String::new();
    let _ = writeln!(out, "trait {}:", t.name);
    for m in &t.methods {
        let params: Vec<String> = m
            .params
            .iter()
            .map(|(n, ty)| {
                // `self: Self` is written `self`, which is the notation the surface uses and the
                // one the parser gives the implicit type back to.
                if n.as_ref() == "self" && ty.con_name() == Some("Self") {
                    "self".to_string()
                } else {
                    format!("{n}: {ty}")
                }
            })
            .collect();
        let uses = if m.effects.is_empty() {
            String::new()
        } else {
            format!(
                " uses {}",
                m.effects
                    .iter()
                    .map(|e| e.name())
                    .collect::<Vec<_>>()
                    .join(", ")
            )
        };
        let _ = writeln!(
            out,
            "    def {}({}) -> {}{uses}",
            m.name,
            params.join(", "),
            m.ret
        );
    }
    out
}

fn render_impl(i: &ImplSig) -> String {
    let params = if i.params.is_empty() {
        String::new()
    } else {
        format!(
            "[{}]",
            i.params
                .iter()
                .map(|p| p.to_string())
                .collect::<Vec<_>>()
                .join(", ")
        )
    };
    let header = format!("impl{params} {} for {}", i.trait_name, i.target);
    if i.effects.is_empty() {
        return header;
    }
    // A method that performs something publishes what: a caller in another module resolves through
    // this header and has nowhere else to learn it (`docs/27` §27.7). A pure method says nothing,
    // so an impl of a pure trait reads exactly as it did before this existed.
    let mut out = header;
    out.push_str(":\n");
    for (name, row) in &i.effects {
        let atoms: Vec<String> = row.iter().map(|e| e.name()).collect();
        // `def add() uses …` — a bodyless `def` with an empty parameter list, because that is
        // already a shape the reader has: the trait supplies the parameters, and repeating them
        // here would be the second copy §37's impl rule exists to refuse.
        let _ = writeln!(out, "    def {name}() uses {}", atoms.join(", "));
    }
    out.pop();
    out
}

fn trait_signature(t: &TraitSig) -> String {
    let mut out = format!("trait {}{{", t.name);
    for m in &t.methods {
        let _ = write!(
            out,
            "{}({}) -> {} !{{{}}};",
            m.name,
            m.params
                .iter()
                .map(|(n, ty)| format!("{n}: {ty}"))
                .collect::<Vec<_>>()
                .join(", "),
            m.ret,
            m.effects
                .iter()
                .map(|e| e.name())
                .collect::<Vec<_>>()
                .join(",")
        );
    }
    out.push('}');
    out
}

fn impl_signature(i: &ImplSig) -> String {
    format!(
        "impl[{}] {} for {}",
        i.params.join(","),
        i.trait_name,
        i.target
    )
}

/// The ` uses …` clause of a signature, or nothing for a row with no atoms in it.
///
/// Its own function because two things write it: a published signature, and the inlay hint that
/// offers an *inferred* row as the clause an author could paste into one
/// ([`crate::editor::Editor::hints`]). A hint spelling the row its own way would be a second
/// renderer of the thing §4.6 says there is only one of, and the way it would go wrong is silent —
/// the hint reads plausibly and the signature it suggests does not parse.
pub fn render_uses(effects: &[Effect]) -> String {
    if effects.is_empty() {
        return String::new();
    }
    format!(
        " uses {}",
        effects
            .iter()
            .map(|e| e.name())
            .collect::<Vec<_>>()
            .join(", ")
    )
}

/// One published name, as a `.becki` line.
///
/// Public because `beck lsp` shows it on hover, and `docs/04` §4.6 forbids a second renderer: what
/// an editor says a name's signature is has to be what `beck iface` publishes it as.
pub fn render_item(i: &Item) -> String {
    let uses = render_uses(&i.effects);
    match &i.kind {
        Kind::Function {
            typarams,
            params,
            ret,
        } => format!(
            "def {}{}({}) -> {ret}{uses}\n",
            i.name,
            if typarams.is_empty() {
                String::new()
            } else {
                format!(
                    "[{}]",
                    typarams
                        .iter()
                        .map(|t| match i.bounds.iter().find(|(p, _)| p == t) {
                            Some((_, traits)) => format!(
                                "{t}: {}",
                                traits
                                    .iter()
                                    .map(|x| x.to_string())
                                    .collect::<Vec<_>>()
                                    .join(" + ")
                            ),
                            None => t.to_string(),
                        })
                        .collect::<Vec<_>>()
                        .join(", ")
                )
            },
            params
                .iter()
                .map(|(n, t)| format!("{n}: {t}"))
                .collect::<Vec<_>>()
                .join(", ")
        ),
        Kind::Signal { ty } => format!("def {}() -> {ty}{uses}\n", i.name),
    }
}

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

    fn iface_of(src: &str) -> Interface {
        let (placed, d, map) = compile_str("todo.beck", src);
        assert!(!d.has_errors(), "{}", d.render(&map));
        Interface::of(&placed.expect("it compiles").program)
    }

    #[test]
    fn an_interface_carries_placement_effects_and_types() {
        // §3.6's rule, item by item: "Placement, effects, and event/command types are part of a
        // module's published signature."
        let i = iface_of(crate::split::tests::TODO);
        let todos = i.item("todos").expect("the signal is published");
        assert_eq!(todos.tier, Tier::Data);
        assert_eq!(todos.effects, vec![Effect::Durable]);
        assert!(matches!(todos.kind, Kind::Signal { .. }));
        assert!(i.item("apply_event").is_some());
        // The event and command unions are part of it, because they are the wire.
        assert!(i.types.iter().any(|t| t.name().as_ref() == "Event"));
        assert!(i.types.iter().any(|t| t.name().as_ref() == "Command"));
        // The prelude is not: `Envelope` and `Session` belong to the language, not the module.
        assert!(!i.types.iter().any(|t| t.name().as_ref() == "Envelope"));
    }

    #[test]
    fn a_body_edit_does_not_change_the_interface_digest() {
        // The firewall, in one assertion. This is the property separate compilation is built on:
        // §3.6's "body edits don't invalidate downstream modules".
        let before = iface_of(crate::split::tests::TODO);
        let edited = crate::split::tests::TODO.replace(
            r#""done" if t.done else """#,
            r#""done" if t.done else " ""#,
        );
        let after = iface_of(&edited);
        assert_eq!(before.digest(), after.digest());
        assert_eq!(before, after);
    }

    #[test]
    fn widening_an_effect_changes_the_digest() {
        // §3.6: "effect widening is a breaking API change". It cannot be one if it is invisible.
        let before = iface_of(crate::split::tests::TODO);
        let widened = crate::split::tests::TODO.replace(
            "def owned(s: State, p: Proposal, id: Id, evs: list[Event]) -> Result[list[Event], Rejection]:",
            "def owned(s: State, p: Proposal, id: Id, evs: list[Event]) -> Result[list[Event], Rejection] uses net.out(audit.example.com):",
        );
        let after = iface_of(&widened);
        assert_ne!(
            before.digest(),
            after.digest(),
            "a library that starts phoning home cannot do so silently"
        );
        // …and the new atom is in the published row, by name, with its host.
        let owned = after.item("owned").expect("owned is published");
        assert!(owned
            .effects
            .contains(&Effect::NetOut("audit.example.com".into())));
    }

    #[test]
    fn widening_an_effect_on_the_view_path_does_not_merely_change_the_digest() {
        // The stronger half of the same story, and the one worth having a test of its own: adding
        // `net.out(a-host)` to a function the *view* calls does not produce a new interface to
        // review. It produces a compile error, because the page runs in a browser and a browser
        // cannot reach a named host. The API change is caught before it is an API.
        let widened = crate::split::tests::TODO.replace(
            "def done_class(t: Todo) -> Str:",
            "def done_class(t: Todo) -> Str uses net.out(telemetry.example.com):",
        );
        let (_, d, _) = compile_str("todo.beck", &widened);
        let codes: Vec<&str> = d.iter().map(|x| x.code).collect();
        assert!(codes.contains(&"B0401"), "got {codes:?}");
    }

    #[test]
    fn changing_a_placement_changes_the_digest() {
        let before = iface_of(crate::split::tests::TODO);
        let moved = crate::split::tests::TODO.replace("@on(data)\ntodos", "@on(server)\ntodos");
        assert_ne!(before.digest(), iface_of(&moved).digest());
    }

    #[test]
    fn an_interface_round_trips_through_its_file_form() {
        // Rendered, re-read, and identical — otherwise the checked-in file and the compiler's idea
        // of the contract could drift, which is the failure the file exists to prevent.
        let original = iface_of(crate::split::tests::TODO);
        let text = original.render();
        let mut diags = Diagnostics::new();
        let mut map = SourceMap::new();
        let reread = Interface::parse("todo", &text, &mut map, &mut diags);
        assert!(!diags.has_errors(), "{}\n---\n{text}", diags.render(&map));
        assert_eq!(
            original.digest(),
            reread.digest(),
            "rendered:\n{text}\n\noriginal {original:#?}\n\nreread {reread:#?}"
        );
    }

    #[test]
    fn the_import_lines_survive_the_file_form() {
        // The digest deliberately excludes them, so the round-trip test above cannot see them go.
        // They still have to come back: `Interface::of` reads the list the *checker* was given, so
        // a contract parsed with none supplied would report an empty `imports` while its own file
        // said otherwise — and re-rendering it would drop the lines the reader needs to resolve
        // what it publishes.
        let src = "\
import vocab

model Book:
    cost: Int
";
        let mut diags = Diagnostics::new();
        let mut map = SourceMap::new();
        let reread = Interface::parse("goods", src, &mut map, &mut diags);
        assert_eq!(
            reread.imports,
            vec!["vocab".to_string()],
            "the file says what it imports, whatever the caller supplied"
        );
        assert!(
            reread.render().contains("import vocab"),
            "and rendering it again keeps them:\n{}",
            reread.render()
        );
    }

    /// The same, for a library — which is what a module publishing only types and functions is.
    fn iface_of_library(src: &str) -> Interface {
        let (placed, d, map) = crate::compile_or_library_str("g.beck", src);
        assert!(!d.has_errors(), "{}", d.render(&map));
        Interface::of(&placed.expect("it compiles").program)
    }

    /// A library whose published types are parameterised, through the file form and back.
    const GENERIC: &str = "\
model Stamped[T]:
    at: Int
    what: T

union Verdict[T]:
    Waiting(item: T)
    Failed(item: T, why: Str)

type Trail[T] = list[Stamped[T]]

def stamp[T](at: Int, what: T) -> Stamped[T]:
    return Stamped(at=at, what=what)

def length(t: Trail[Str]) -> Int:
    return list_len(t)

def held(v: Verdict[Str]) -> Str:
    match v:
        case Waiting(item):
            return item
        case Failed(item, why):
            return why
";

    #[test]
    fn a_parameterised_declaration_round_trips_through_the_file_form() {
        // A `.becki` is source, and the checker holds a declaration's parameters positionally. If
        // rendering did not put the names back, the file would say `what: ?1000000` and nothing
        // would read it again.
        let original = iface_of_library(GENERIC);
        let text = original.render();
        assert!(text.contains("model Stamped[T]:"), "{text}");
        assert!(text.contains("what: T"), "{text}");
        assert!(text.contains("union Verdict[T]:"), "{text}");
        assert!(text.contains("type Trail[T] = list[Stamped[T]]"), "{text}");
        assert!(
            !text.contains('?'),
            "no positional variable escapes:\n{text}"
        );

        let mut diags = Diagnostics::new();
        let mut map = SourceMap::new();
        let reread = Interface::parse("g", &text, &mut map, &mut diags);
        assert!(!diags.has_errors(), "{}\n---\n{text}", diags.render(&map));
        assert_eq!(original.digest(), reread.digest(), "rendered:\n{text}");
    }

    #[test]
    fn the_same_declaration_at_two_arguments_is_two_boundaries() {
        // The question `sicp/refusals/generic-type.beck` asked of `--wire-compat`: whether
        // `Stamped[Int]` and `Stamped[Str]` are the same boundary. They are not, and the structural
        // hash is where that is decided — a declaration is published once, parameterised, and every
        // *mention* of it carries the arguments that make it a type.
        let ints = iface_of_library(&GENERIC.replace("Trail[Str]", "Trail[Int]"));
        let strs = iface_of_library(GENERIC);
        assert_ne!(ints.digest(), strs.digest());
        assert_eq!(
            ints.types.iter().find(|t| t.name().as_ref() == "Stamped"),
            strs.types.iter().find(|t| t.name().as_ref() == "Stamped"),
            "the declaration itself did not change; only what a signature applied it to"
        );
    }

    #[test]
    fn an_interface_with_a_body_in_it_is_refused() {
        let mut diags = Diagnostics::new();
        let mut map = SourceMap::new();
        Interface::parse(
            "x",
            "def f(a: Int) -> Int:\n    return a\n",
            &mut map,
            &mut diags,
        );
        assert!(diags.iter().any(|d| d.code == "B0600"));
    }
}